docs/README.md

Documentation Process for NeMo

Building the Documentation

1. Create and activate a virtual environment.

2. Install the documentation dependencies:

   $ python3 -m pip install -r requirements/requirements_docs.txt
   

3. Build the documentation:

   $ make -C docs html
   

Checking for Broken Links

1. Build the documentation, as described in the preceding section, but use the following command:

   make -C docs clean linkcheck
   

2. Run the link-checking script:

   ./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.

{
  "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:.

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: