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

Add Sphinx for project documentation #1457

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

kfkitsune
Copy link
Member

This can be tweaked later, but this should provide a decent 'starting point', for lack of a better term.

So assuming I have this correct, this should be automatically creating the documentation for both libweasyl and weasyl, and when pushed to the main branch, the added workflow will publish to GitHub Pages.

Not quite sure where to add the command to rebuild the HTML; to be honest, the fact that we're abstracting packages into a Docker container is a tad cumbersome, and to get it built as it was, I needed to have a venv on my host via Poetry, and poetry install --with=docs --sync to get Sphinx installed to be able to build it. There's probably some little thing I am overlooking, but... I'm hoping this provides a good starting point.

This can be tweaked later, but this should provide a decent 'starting point', for lack of a better term.
@charmander charmander added the docs Documentation-related issues label Nov 1, 2024
This is probably at a 'good enough' state, for the moment.
@charmander
Copy link
Contributor

charmander commented Nov 7, 2024

I appreciate the effort, and the rendered output looks very nice, but I don’t think the added machinery is worth it. The additional developments docs are good, though, and would be a good thing to link to as a normal Markdown document somewhere in the README, without duplication.

@kfkitsune
Copy link
Member Author

The additional developments docs are good, though, and would be a good thing to link to as a normal Markdown document somewhere in the README, without duplication.

Do you mean the additional information in docs/source/commands.md?

Also it's not a problem; this is easy enough to recreate if at some point in the future we want Sphinx documentation. The Sphinx extensions I used for this did the vast majority of the heavy lifting, and the only real complexity was having to deal with with wzl, since for Sphinx to build the documentation weasyl and libweasyl installed for the documentation to build (which means installing the docs dependencies as they are needed).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation-related issues
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants