Spaces:
Runtime error
Runtime error
| # 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: | |
| ``` | |