You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can include static pages (like *index* or *FAQ*) in the generated documentation, following the steps below:
132
132
133
-
- create a directory (e.g., `static-pages/`) with `.html`or `.md` files
133
+
- create a directory (e.g., `static-pages/`) with `.md` (preferred) or `.html` files
134
134
- each file represents a page and should contain its the body content
135
135
- run the generator with:
136
136
@@ -142,28 +142,37 @@ You can include static pages (like *index* or *FAQ*) in the generated documentat
142
142
**Important: The static pages are not designed to offer the functionality of a full-fledged SSG. If you want more control over the pages, is advised to use an SSG, such as Jekyll, for user documentation.**
143
143
144
144
Additional notes:
145
-
-it is possible to use relative links between pages
145
+
-It is possible to use relative links between pages. (Links to `.md` files are automatically updated to point to the correct output HTML files in the generated documentation.)
146
146
- you can include images, JS, or any other resources in the static pages directory, and then reference them from the pages
147
-
- to add custom CSS styles, put them into `/css/styles.css` and they will be included automatically (however, use custom styles only for minor tweaks, rather than completely changing the overall appearance of the page)
148
147
- it is possible to put the pages (and other files) into subdirectories of the `static-pages/` directory (however, pages nested three or more levels deep will not appear in the top menu)
148
+
- in case you use HTML pages, to add custom CSS styles, put them into `/css/styles.css` and they will be included automatically (however, use custom styles only for minor tweaks, rather than completely changing the overall appearance of the page)
149
149
150
-
#### Example
151
150
152
-
Directory structure:
151
+
## Example
152
+
153
+
Example directory structure:
153
154
```
154
155
static-pages/
155
-
index.html
156
-
FAQ.md
156
+
index.md
157
+
FAQ.html
158
+
```
159
+
160
+
`index.md`
161
+
```markdown
162
+
# MyLibrary Reference Documentation
163
+
164
+
This page contains the reference documentation for MyLibrary.
165
+
166
+
## Installation
167
+
To install, run `dotnet tool install my-library`.
157
168
```
158
169
159
-
`index.html`
170
+
`FAQ.html`
160
171
```html
161
-
<h1>
162
-
MyLibrary reference documentation
163
-
</h1>
164
-
<div>
165
-
This page contains the reference documentation of MyLibrary.
166
-
</div>
172
+
<h1>FAQ</h1>
173
+
174
+
<h6>Q1: How to install the library?</h6>
175
+
<divclass="fw-light">A1: ...</div>
167
176
```
168
177
169
178
`FAQ.md`
@@ -176,14 +185,14 @@ static-pages/
176
185
177
186
### Documentation versioning
178
187
179
-
You can optionally generate versioned documentation, allowing users to switch between multiple versions.
180
-
To do this, it is necessary to use the `--doc-version` option.
188
+
You can optionally generate versioned documentation, which allows users to switch between multiple versions.
189
+
To do this, use the `--doc-version` option.
181
190
182
-
The version can be switched using the dropdown in the bottom menu.
191
+
The version can then be switched using the dropdown menu at the bottom of the page.
183
192
184
193
#### Examples
185
194
186
-
Generate two versions of the documentation, using these commands (the output directory needs to be the same):
195
+
Generate two versions of the documentation using these commands (the output directory must be the same):
The documentation versions do not necessarily have to match the library versions.
196
-
For instance, we may create two documentation versions, one showing the public API, and the other including even private members, as illustrated below:
205
+
For example, you may create two documentation versions: one showing only the public API, and another including private members, as illustrated below:
An example of versioned documentation can be found [here](https://vl-cz.github.io/refdocgen-demo-refdocgen/index.html). \
204
-
Note that the documentations consists of two versions: `v-public` - displays only the public API and `v-private` displaying all types and members
212
+
An example of versioned documentation can be found [here](https://vl-cz.github.io/refdocgen-demo-example-library/index.html).
205
213
206
214
### YAML configuration
207
-
Instead of using command line arguments, it is possible to use a YAML file for configuration. \
208
-
Then:
209
-
- we don't need to repeat the options every time
210
-
- the configuration can be easily shared
215
+
You can use a YAML file to configure RefDocGen instead of specifying options on the command line. This approach makes it easy to reuse and share your configuration.
211
216
212
217
The YAML file can be generated automatically using the `--save-config` flag (preferred) or created manually.
213
218
It is recommended to name the file `refdocgen.yaml`.
214
219
215
-
The structure of YAML and commandline configuration is very similar:
220
+
YAML configuration closely mirrors the command-line options:
216
221
217
-
-all the keys in YAML have the same name as the matching command-line option (without the starting dashes), e.g. the `output-dir` key corresponds to the `--output-dir` option
218
-
-the only mandatory key is the `input` (similar to the command-line configuration)
219
-
-`save-config` option is not supported, as it does not make sense here
220
-
-the default values are the same as in the command-line configuration
222
+
-Each YAML key matches its corresponding command-line option (without leading dashes). For example, the `output-dir` key in YAML corresponds to the `--output-dir` option.
223
+
-The only required key is `input`, just as on the command line.
224
+
-The `save-config` option is not supported in YAML, as it doesn't make sense here
225
+
-Default values are the same as those used for command-line options.
221
226
222
-
#### Examples
227
+
#### Example
223
228
224
-
The following command results in creating the YAML displayed below:
229
+
The following command generates a YAML configuration file as shown below:
225
230
226
231
```bash
227
232
refdocgen MyLibrary.sln
@@ -253,6 +258,10 @@ exclude-namespaces:
253
258
254
259
The next time we want to use the same configuration, we just need to run `refdocgen refdocgen.yaml` and the configuration will be loaded from the YAML.
255
260
261
+
### Templates
262
+
Currently, only the `Default` documentation template is available.
263
+
However, it is possible to create custom templates, as described in the [official documentation](https://vl-cz.github.io/refdocgen/templates/available-templates.html).
<see cref="..."> (link not resolved) <code class="refdocgen-see-cref-not-found">
51
+
<seealso cref="..."> (link not resolved) <code class="refdocgen-seealso-cref-not-found">
52
52
```
53
53
54
54
All of these CSS classes can be styled as needed. For example:
@@ -59,6 +59,7 @@ All of these CSS classes can be styled as needed. For example:
59
59
}
60
60
```
61
61
62
+
Ideally, use the `styles.css` file in `Todo/Templates/Static`, as this directory is copied to the output documentation folder.
62
63
You can also inherit existing CSS classes using a CSS preprocessor, similar to how the default UI does it (see `TemplateProcessors/Default/Templates/Scss/styles.scss`).
0 commit comments