Developer Documentation

[ollimeier]

Longterm we need some kind of code documentation. This popped up in todays meeting. The question is, what are best practices currently for code documentations? We were thinking about inline code documentation which can be translated to a eg a webpage docu, similar to https://fonttools.readthedocs.io/en/latest/

Any ideas or suggestions?

[fabiocaccamo]

My 3 favourite solutions in order of preference:

• MKDocs with Material theme
• ReadTheDocs
• GitHub documentation written in markdown (easy to manage for everyone)

I don’t know if they are fully-compatible with a JS project, I used them in Python/Django context.

In the JS ecosystem I tried different tools, but long time ago, in the end I opted for jsdoc + jsdoc-to-markdown. The latter is cool because it converts documentation like the example below directly to markdown:

/**
 * { function_description }
 *
 * @param {<type>} str The string
 * @return {string} { description_of_the_return_value }
 */
encode: function (str) {
   // 
}

Anyway... as personal preference, I would opt to have final documentation written in Markdown and not in reStructuredText.

[ollimeier]

@justvanrossum @JeremieHornus Any comments, ideas from your side?

[ollimeier]

Links we may want to add somewhere in the documentation: https://developer.mozilla.org/en-US/docs/Web/API/Path2D https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API

[justvanrossum]

What I'm most curious about at this point is: how does the fonttools documenation integrate separate doc files (fonttools/Docs) with inline documentation in the code.

And: how can we do the same for JavaScript.

[ollimeier]

It looks like fonttools docs are made with sphinx-doc. As far as I was able to figure out (so far), sphinx is mainly 'restructuredtext', which is not preferred by @fabiocaccamo . But it can also handle MarkDown with an extension: https://www.sphinx-doc.org/en/master/usage/markdown.html

sphinx is also available for JavaScript: https://pypi.org/project/sphinx-js/

[justvanrossum]

I also prefer MarkDown, but this sounds like a good solution.

Does MkDocs also support sphinx-doc somehow? FWIW, fonttools uses readthedocs.

How does MkDocs compare to readthedocs, and why do you prefer it, @fabiocaccamo?

[ollimeier]

@justvanrossum Looks like sphinx to me: https://github.com/fonttools/fonttools/blob/a3b9eddcafcab4002b42d38466954cddd7ef68c2/Doc/docs-requirements.txt#L1C1-L1C7

[ollimeier]

I have no experiences with setting up such thing. I am not sure how to continue.

[fabiocaccamo]

I don't have a lot of experience with any of these tools, but from what I've been able to see/test:

• MkDocs is a lightweight documentation generator that is particularly well-suited for creating project documentation in Markdown format. It's commonly used for creating simple, clean and easy-to-navigate documentation.

• Sphinx is probaly a more powerful and feature-rich documentation generator that is commonly used for larger projects and more complex documentation needs. It supports both Markdown and reStructuredText.

I think that MkDocs is more intuitive and simple to use, which should not be underestimated if we want to think long term and ease of use for potential collaborators.

Both MkDocs and Sphinx are compatible with ReadTheDocs: https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html

[justvanrossum]

My question is: can MkDocs extract source docs from source files, like sphinx does?

[fabiocaccamo]

No, it can't, but it should be possible to take advantage of the best of both tools to arrive at a solution like this:

• Generate documentation from source files using Sphinx
• Convert generated documentation to Markdown
• Configure MkDocs to include external Markdown
• Use generated Markdown documentation with MkDocs
• Configure MkDocs to handle both: static documentation written by hand and dynamic documentation generated using Sphinx.

[ollimeier]

For reference, we need to investigate more into this topic. Together with @justvanrossum we are a bit optimistic when about: https://pypi.org/project/sphinx-js/ It seems it's supported regularly (two releases per year)