This PR uses sphinx to generate a simple man page.
context
Until recently, pyee used sphinx to generate its documentation. However, I recently decided to switch to mkdocs due to better markdown support in docstring-based documentation. I also felt that mkdocs had better theming, and liked how it did configuration better. For the most part, I'm happy with this move.
However, it was pointed out in #140 that sphinx can generate other kinds of documentation aside from HTML, namely man pages. While I didn't want to switch back to sphinx, I did see value in generating a man page, and didn't otherwise have a strong opinion about reintroducing sphinx to the build.
description
Practically speaking, there are a number of compatibility issues between sphinx and mkdocs which limit sphinx's effectiveness:
Sphinx's includes can't account for differences in format - in other words, you can't include markdown content in an rst file.
Sphinx's autodoc syntax is completely different than mdocstrings' autodoc format - in other words, sphinx won't know what to do with my api.md.
Sphinx's autodoc and markdown support don't play nice together - in other words, you can't autodoc mkdocstrings-style docstrings with sphinx.
Ultimately, the approach I took was to create an isolated man.rst that includes some basic documentation of the module, but ultimately delegates to the mkdocs API documentation. The result is far from comprehensive and will probably be disappointing. Unfortunately, this is practically the best I can do, barring switching back to sphinx completely - which I don't want to do.
usage/testing
First, this adds a new just task, just sphinx TARGET, which is roughly equivalent to what the standard sphinx Makefile does. It can technically be used to generate any format sphinx supports, though its content will be limited to what's intended for a man page.
Second, it adds another new just task, just man, which generates the man page with sphinx and then opens it with man -l. This can be used alongside just docs to generate/preview documentation.
Finally, the mkdocs step has been moved to its own task, just mkdocs, and build-docs now generates both the mkdocs-based html docs and the sphinx-based man page.
This PR uses sphinx to generate a simple man page.
context
Until recently, pyee used sphinx to generate its documentation. However, I recently decided to switch to mkdocs due to better markdown support in docstring-based documentation. I also felt that mkdocs had better theming, and liked how it did configuration better. For the most part, I'm happy with this move.
However, it was pointed out in #140 that sphinx can generate other kinds of documentation aside from HTML, namely man pages. While I didn't want to switch back to sphinx, I did see value in generating a man page, and didn't otherwise have a strong opinion about reintroducing sphinx to the build.
description
Practically speaking, there are a number of compatibility issues between sphinx and mkdocs which limit sphinx's effectiveness:
Ultimately, the approach I took was to create an isolated
man.rstthat includes some basic documentation of the module, but ultimately delegates to the mkdocs API documentation. The result is far from comprehensive and will probably be disappointing. Unfortunately, this is practically the best I can do, barring switching back to sphinx completely - which I don't want to do.usage/testing
First, this adds a new just task,
just sphinx TARGET, which is roughly equivalent to what the standard sphinx Makefile does. It can technically be used to generate any format sphinx supports, though its content will be limited to what's intended for a man page.Second, it adds another new just task,
just man, which generates the man page with sphinx and then opens it withman -l. This can be used alongsidejust docsto generate/preview documentation.Finally, the mkdocs step has been moved to its own task,
just mkdocs, andbuild-docsnow generates both the mkdocs-based html docs and the sphinx-based man page.Closes #140.