Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build man pages #141

Merged
merged 6 commits into from
Nov 22, 2023
Merged

Build man pages #141

merged 6 commits into from
Nov 22, 2023

Conversation

jfhbrook
Copy link
Owner

@jfhbrook jfhbrook commented Nov 22, 2023

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:

  1. Sphinx's includes can't account for differences in format - in other words, you can't include markdown content in an rst file.
  2. 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.
  3. 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.

Closes #140.

@jfhbrook jfhbrook merged commit d36f0de into main Nov 22, 2023
6 checks passed
@jfhbrook jfhbrook deleted the sphinx-redux branch November 22, 2023 23:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Generate non-HTML (man page) docs (with sphinx)
1 participant