subhankarg's picture
Upload folder using huggingface_hub
0558aa4 verified
# 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:
```