Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.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 withman -l
. This can be used alongsidejust docs
to generate/preview documentation.Finally, the mkdocs step has been moved to its own task,
just mkdocs
, andbuild-docs
now generates both the mkdocs-based html docs and the sphinx-based man page.Closes #140.