Documentation #36243
Updated by Ernesto Puerta over 5 years ago
h3. Intro This is review of a bunch of tools suitable for documenting the code. This is aimed at complementing the existing doc sources: * Ceph docs (doc/mgr/dashboard.rst): user focus * README: user focus * HACKING.rst: dev focus (introductory) * Swagger API docs: dev focus (as long as API is not meant to be consumed externally). Some missing doc areas would be: * Architecture docs * Implementation docs Both things may be covered with doc generators (Doxygen, Sphinx, etc). Due to the diversity of languages we may find: * **General purpose doc generators** ** "**Sphinx**":http://www.sphinx-doc.org/en/master/ is extensively used in Ceph docs. There are different plugins Sphinx has support for JS support, most based on "JSDoc":http://usejsdoc.org/: "sphinx-js":https://pypi.org/project/sphinx-js/. by means of external libraries (not specifically TS or Angular): "sphinx-js":https://pypi.org/project/sphinx-js/ * **Language-specific generatos**: ** "**Compodoc**":https://compodoc.app/guides/getting-started.html is an Angular focused tool for auto-doc'ing, also parsing JSDoc tags. ** "**TypeDoc**":http://typedoc.org/api/: Typescript specific. auto-doc'ing.