Project

General

Profile

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.

Back