Find a documentation engine #1

jfinkhaeuser commented 2020年02月05日 10:50:31 +01:00

The plan is to publish documentation of different packages either on subdomains of interpeer.io, or within URL paths they "own".

Since the main website is static HTML generated by pelican, it would be nice to find a python based documentation engine that generates the documentation. Maybe Sphinx. We'll see.

The plan is to publish documentation of different packages either on subdomains of interpeer.io, or within URL paths they "own". Since the main website is static HTML generated by pelican, it would be nice to find a python based documentation engine that generates the documentation. Maybe Sphinx. We'll see.

jfinkhaeuser commented 2020年02月05日 10:52:15 +01:00

mentioned in issue #2

mentioned in issue #2

jfinkhaeuser commented 2020年02月05日 10:59:28 +01:00

One approach:

• Document in Doxygen syntax or Sphinx syntax, depending on the sources.
• Use Breathe for converting from Doxygen to Sphinx.
• Then use Sphinx to generate the document(s).

One approach: - Document in [Doxygen](http://doxygen.nl/) syntax or [Sphinx](https://www.sphinx-doc.org/en/stable/) syntax, depending on the sources. - Use [Breathe](https://breathe.readthedocs.io/en/latest/) for converting from Doxygen to Sphinx. - Then use Sphinx to generate the document(s).

jfinkhaeuser commented 2020年02月05日 11:04:52 +01:00

Meson and GStreamer both use hotdoc. It has extensions for scanning Python or C source files, but it's unclear whether the latter works for C++.

Meson and GStreamer both use [hotdoc](https://github.com/hotdoc/hotdoc). It has extensions for scanning Python or C source files, but it's unclear whether the latter works for C++.

jfinkhaeuser commented 2020年02月05日 11:55:54 +01:00

Slate creates nice documentation, but it seems to be for web APIs and doesn't extract docs from programming language files.

[Slate](https://github.com/slatedocs/slate) creates nice documentation, but it seems to be for web APIs and doesn't extract docs from programming language files.

jfinkhaeuser commented 2020年02月05日 11:58:03 +01:00

Similar to Slate is Hugo.

Similar to Slate is [Hugo](https://gohugo.io/).

jfinkhaeuser commented 2020年02月05日 13:24:00 +01:00

https://www.writethedocs.org/guide/tools/sphinx-themes/

https://www.writethedocs.org/guide/tools/sphinx-themes/

jfinkhaeuser commented 2023年01月11日 11:39:18 +01:00

For the time being, we're using Hugo for the site, and therefore also for the documentation sub-section. But the workflow is not very satisfying; extracting the Hugo specific metadata from e.g. markdown repos is far from automatic.

I suspect it'll come down to creating a site similar to specs.interpeer.io which is docs.interpeer.io, and which will contain generated docs. Then whatever is at the main site is just an introduction similar to how it is now.

For the time being, we're using Hugo for the site, and therefore also for the documentation sub-section. But the workflow is not very satisfying; extracting the Hugo specific metadata from e.g. markdown repos is far from automatic. I suspect it'll come down to creating a site similar to specs.interpeer.io which is docs.interpeer.io, and which will contain generated docs. Then whatever is at the main site is just an introduction similar to how it is now.

jfinkhaeuser commented 2023年02月04日 04:40:42 +01:00

Looking into this more, it seems a possible pipeline is this:

1. Use doxygen to extract API documentation and generate XML.
2. Use asciidoxy to combine external and API documentation and generate plain asciidoc.
3. Use asciidoctor, but with a shim (https://ratfactor.com/hugo-adoc-html5s), configured via a local script and setting the PATH appropriately.
4. Use Hugo's support for asciidoc as an input format via asciidoctor.

It's a pretty convoluted pipeline, but it has some additional benefit in that the first step(s) can be done with the source repository as its input, leaving the XML file in the website repo. We can then use the remainder of the steps to generate the site, tweak the layout, etc.

Looking into this more, it seems a possible pipeline is this: 1. Use doxygen to extract API documentation and generate XML. 1. Use asciidoxy to combine external and API documentation and generate plain asciidoc. 1. Use asciidoctor, but with a shim (https://ratfactor.com/hugo-adoc-html5s), configured via a local script and setting the PATH appropriately. 1. Use Hugo's support for asciidoc as an input format via asciidoctor. It's a pretty convoluted pipeline, but it has some additional benefit in that the first step(s) can be done with the source repository as its input, leaving the XML file in the website repo. We can then use the remainder of the steps to generate the site, tweak the layout, etc.