Draft: Enable a minimal docs linkcheck build

[mikemckiernan]

What does this PR do ?

Make it possible to perform a docs linkcheck build.

Collection: [Note which collection this PR will affect]

Changelog

• chore(docs): Add a docs linkcheck build.

Usage

• Refer to docs/README.md.

GitHub Actions CI

The Jenkins CI system has been replaced by GitHub Actions self-hosted runners.

The GitHub Actions CI will run automatically when the "Run CICD" label is added to the PR.
To re-run CI remove and add the label again.
To run CI on an untrusted fork, a NeMo user with write access must first click "Approve and run".

Before your PR is "Ready for review"

Pre checks:

• Make sure you read and followed Contributor guidelines
• Did you write any new necessary tests?
• Did you add or update any necessary documentation?
• Does the PR affect components that are optional to install? (Ex: Numba, Pynini, Apex etc)
  • Reviewer: Does the PR have correct import guards for all optional libraries?

PR Type:

• New Feature
• Bugfix
• Documentation

If you haven't finished some of the above items you can still open "Draft" PR.

Who can review?

Anyone in the community is free to review the PR once the checks have passed.
Contributor guidelines contains specific people who can review PRs to various areas.

Additional Information

• Related to # (issue)

[github-actions]

beep boop 🤖: 🙏 The following files have warnings. In case you are familiar with these, please try helping us to improve the code base.

---

Your code was analyzed with PyLint. The following annotations have been identified:

************* Module conf
docs/source/conf.py:242:0: C0116: Missing function or method docstring (missing-function-docstring)

-----------------------------------
Your code has been rated at 9.82/10

---

Mitigation guide:

• Add sensible and useful docstrings to functions and methods
• For trivial methods like getter/setters, consider adding # pylint: disable=C0116 inside the function itself
• To disable multiple functions/methods at once, put a # pylint: disable=C0116 before the first and a # pylint: enable=C0116 after the last.

By applying these rules, we reduce the occurance of this message in future.

Thank you for improving NeMo's documentation!

[ko3n1g]

LGTM, thanks!

[ko3n1g]

Is it scope of this PR to add it into our CI?

[mikemckiernan]

Is it scope of this PR to add it into our CI?

I can give it a whirl--just that before I got into it, I wanted confirmation that it was welcome. Hopefully some time this week. If you have something else in mind, PLMK. Thanks!

[mikemckiernan]

I squeezed the linkcheck build into CI and also the script that avoids false positives. The TODOs that come to mind:

• I didn't address dependencies for building the API pages. As a result, there are absurd (!) broken links for what should be local:

  (nlp/nemo_megatron/peft/landing_page: line   31) broken    ../../api.html#adapter-mixin-class - 
  (multimodal/nerf/configs: line    4) broken    ../../core/core.html - 
  (core/adapters/intro: line    8) broken    ../../starthere/tutorials.html - 
  (asr/speech_classification/configs: line   26) broken    ../api.html#Datasets - 
  

• After pecking away at the links that are broken vs false positives, remove the || true from ./docs/check_for_broken_links.sh || true

Miraculous improvements are difficult to come by. This approach is one way to gradually improve. PLMK what you'd like changed or enhanced.

[ko3n1g]

Is it scope of this PR to add it into our CI?

I can give it a whirl--just that before I got into it, I wanted confirmation that it was welcome. Hopefully some time this week. If you have something else in mind, PLMK. Thanks!

It would be awesome and highly appreciated to have lintcheckers for docs in our CI! :)

[ko3n1g]

I squeezed the linkcheck build into CI and also the script that avoids false positives. The TODOs that come to mind:

• I didn't address dependencies for building the API pages. As a result, there are absurd (!) broken links for what should be local:

  (nlp/nemo_megatron/peft/landing_page: line   31) broken    ../../api.html#adapter-mixin-class - 
  (multimodal/nerf/configs: line    4) broken    ../../core/core.html - 
  (core/adapters/intro: line    8) broken    ../../starthere/tutorials.html - 
  (asr/speech_classification/configs: line   26) broken    ../api.html#Datasets - 
  

• After pecking away at the links that are broken vs false positives, remove the || true from ./docs/check_for_broken_links.sh || true

Miraculous improvements are difficult to come by. This approach is one way to gradually improve. PLMK what you'd like changed or enhanced.

So docs doesn't like relative links? What's the proper solution to those lints?

[mikemckiernan]

I squeezed the linkcheck build into CI and also the script that avoids false positives. The TODOs that come to mind:

• I didn't address dependencies for building the API pages. As a result, there are absurd (!) broken links for what should be local:

  (nlp/nemo_megatron/peft/landing_page: line   31) broken    ../../api.html#adapter-mixin-class - 
  (multimodal/nerf/configs: line    4) broken    ../../core/core.html - 
  (core/adapters/intro: line    8) broken    ../../starthere/tutorials.html - 
  (asr/speech_classification/configs: line   26) broken    ../api.html#Datasets - 
  

• After pecking away at the links that are broken vs false positives, remove the || true from ./docs/check_for_broken_links.sh || true

Miraculous improvements are difficult to come by. This approach is one way to gradually improve. PLMK what you'd like changed or enhanced.

So docs doesn't like relative links? What's the proper solution to those lints?

AFAIK, there's no Wegovy-like equivalent to looking over each one. I skimmed the first one and here's my thinking:

Source:

The API guide can be found `here <../../api.html#adapter-mixin-class>`__

Hasty assessment:

• That link would have worked in the past if the docs/source/apis.rst file happened to be named api.rst at some point.
• Because that xref uses the .html file suffix and external link syntax, you'd only know it broke it by running the linkcheck build that this PR adds.
• For source-to-source xrefs, the best approach is an internal link syntax like :doc:`apis` . It seems that either the Adapter Mixin class documentation was removed, moved, or I do not have all the library dependencies resolved when I built.

The benefit of the source-to-source internal link syntax is that they are fail-fast and break during the build. You have a chance of noticing and fixing before merging.