[SUGGESTION] Online Developers documentation generated from source code comments by Doxygen?

[Gamester17]

Moved the part of the discussion about Doxygen documentation from #452 to its own issue here:

Can I suggest all (zigpy) developers start using Doxygen formatted inline code documentation in the source code files?

That way the bulk of any Developers documentation does not have to be maintained separately (which then would normally quickly be outdated) and can instead be generated live at any time from the latest code three using documentation generator tools.

https://en.wikipedia.org/wiki/Doxygen

You would really only have to agree to follow a standard for inline code documentation., which should not be too hard as Doxygen is the de facto standard and do support Python. Doxygen, is a documentation system that supports most programming languages today. It can generate html docs documenting a projects source code, by either extracting special tags from the source code (put there by people wanting to make use of doxygen), or doxygen will otherwise attempt to build the documentation from the existing source code.

https://www.doxygen.nl/index.html

CodeDocs will then generate and publish documentation from Doxygen for you, (free to setup with public GitHub repositories).

https://codedocs.xyz/

For example, you can check out the Kodi code documentation generated on codedocs.xyz

https://codedocs.xyz/AlwinEsch/kodi/

There are of course many different standards for inline code documentation and also many documentation generation tools, ex:

https://wiki.python.org/moin/DocumentationTools

[Gamester17]

For example, you can check out the Kodi code documentation generated on codedocs.xyz

https://codedocs.xyz/AlwinEsch/kodi/

A better example might be OpenZWave Online Developers documentation docs generated from source comments by Doxygen:

http://www.openzwave.com/dev/

Also:

If you do "make install" and have Doxygen on your system, a description of the api will be in open-zwave/docs/api/html/index.html

[puddly]

Sphinx is what most Python projects (including https://docs.python.org/) use for generating their documentation.

Some resources:

• https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
• https://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/
• https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

I think we have enough information floating around in the GitHub issues and other Markdown files to get at least something basic started.

[Gamester17]

@puddly & @Adminiuga Please also see #471 by pipiche38

[github-actions]

There hasn't been any activity on this issue recently. Due to the high number of incoming GitHub notifications, we have to clean some of the old issues, as many of them have already been resolved with the latest updates. Please make sure to update to the latest version and check if that solves the issue. Let us know if that works for you by adding a comment 👍 This issue has now been marked as stale and will be closed if no further activity occurs. Thank you for your contributions.

[Hedda]

Sphinx is what most Python projects (including https://docs.python.org/) use for generating their documentation.

Some resources:

• https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
• https://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/
• https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

I think we have enough information floating around in the GitHub issues and other Markdown files to get at least something basic started.

Sphinx still applicable as the preferred syntax format for Python code inline markup documentation?

[github-actions]

There hasn't been any activity on this issue recently. Due to the high number of incoming GitHub notifications, we have to clean some of the old issues, as many of them have already been resolved with the latest updates. Please make sure to update to the latest version and check if that solves the issue. Let us know if that works for you by adding a comment 👍 This issue has now been marked as stale and will be closed if no further activity occurs. Thank you for your contributions.