Spaces:
Runtime error
Runtime error
File size: 2,040 Bytes
0558aa4 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
# Documentation Process for NeMo
## Building the Documentation
1. Create and activate a virtual environment.
1. Install the documentation dependencies:
```console
$ python3 -m pip install -r requirements/requirements_docs.txt
```
1. Build the documentation:
```console
$ make -C docs html
```
## Checking for Broken Links
1. Build the documentation, as described in the preceding section, but use the following command:
```shell
make -C docs clean linkcheck
```
1. Run the link-checking script:
```shell
./docs/check_for_broken_links.sh
```
If there are no broken links, then the script exits with `0`.
If the script produces any output, cut and paste the `uri` value into your browser to confirm
that the link is broken.
```json
{
"filename": "nlp/text_normalization/nn_text_normalization.rst",
"lineno": 247,
"status": "broken",
"code": 0,
"uri": "https://research.fb.com/wp-content/uploads/2019/03/Neural-Models-of-Text-Normalization-for-Speech-Applications.pdf",
"info": "400 Client Error: Bad Request for url: https://research.facebook.com/wp-content/uploads/2019/03/Neural-Models-of-Text-Normalization-for-Speech-Applications.pdf"
}
```
If the link is OK, and this is the case with many URLs that reference GitHub repository file headings,
then cut and paste the JSON output and add it to `docs/false_positives.json`.
Run the script again to confirm that the URL is no longer reported as a broken link.
There may be false positives due to Sphinx not being able to detect links from built html files.
Instead of adding those to the `docs/false_positives.json` file, it would be best to rewrite the
reference using a [:ref:](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref).
For example, instead of writing `Modules <../api.html#modules>` to link to the modules section of
a `api.rst` file, write it as ``:ref:`Modules <asr-api-modules>` ``. And in the `api.rst` file, add
this label before the section being linked to:
```
.. _asr-api-modules:
```
|