Developer documentation: make source code docs more discoverable by uploading docs to Read The Docs

[josephsl]

Hi,

This issue stems from a discussion on NVDA Add-ons list: https://nvda-addons.groups.io/g/nvda-addons/topic/please_do_not_attack_this/79175349?p=,,,20,0,0,0::recentpostdate%2Fsticky,,,20,2,0,79175349

Is your feature request related to a problem? Please describe.

While NVDA's source code is extensive and is a handy reference for add-on authors, a constant criticism is discoverability: although a developer guide and an add-ons guide exists, source code docs is hard to find. This is made complicated by the statement in the NVDA source code readme that declares that dev docs cannot be built in current (Python 3) NVDA releases when in fact it is possible to do so via Sphinx (a companion issue will follow that has to do with inability to build dev docs locally).

As the linked discussion notes, add-on guide, and in some cases, NVDA's own developer guide are inadequate to give add-on developers and outside researchers a chance to read through NVDA's internals. Although the discussion does touch on add-on review process, the bigger issue is lack of documentation.

Describe the solution you'd like

Host NVDA's source code docs on online documentation publishing services. one of these is Read The Docs (readthedocs.org) which hosts dev docs for a variety of open-source projects.

Publishing dev docs on a service such as Read The Docs brings the following advantages:

1. It can expose the current state of NVDA's source code documentation. Doing so will contribute to people pointing out mistakes, omissions, and sending pull requests.
2. It will allow the public to read dev docs for at least alpha snapshots (master branch) as the code changes occur.
3. It can serve as a handy reference for add-on authors and people wishing to contribute further to NVDA Core.

Drawbacks include:

1. Appveyor directives must be modified to publish to Read The Docs and similar services automatically whenever commits are made to at least master, beta, and rc branches.
2. Investments must be made to train would-be contributors on proper documentation strategies (I think not many in the NVDA development circles have necessary skill set or exposure to technical writing yet).

Describe alternatives you've considered

Let people build dev docs locally (next issue), or perhaps enhance the dev guide by providing module overviews and more examples.

Additional context

As noted above, investments must be made to train contributors on how to write effective technical documentation (not just source code, but writings that describe what and how NVDA does things).

Thanks.

[LeonarddeR]

We'll need to convert the doc strings to the proper annotation style before sphinx docs are really usable enough to go on readthedocs.

[josephsl]

Hi,

About Sphinx annotations: agreed - I think that's the most important thing to do once #11972 is merged into master. Doing so will allow folks to send in annotation pull requests.

Thanks.

[Adriani90]

cc: @seanbudd, @gerald-hartig for triaging, I think it is now much easier to get to the source code docs right?

[seanbudd]

@Adriani90 - no this is still blocked by #12971