search

nat-n / poethepoet

A task runner that works well with poetry.
https://poethepoet.natn.io/
MIT License
1.46k stars 59 forks source link

Documentation website #11

Closed nat-n closed 1 year ago

nat-n commented 4 years ago

Poe the poet is growing in complexity to the point where a single readme.rst isn’t the clearest form of documentation. Setting up a documentation website, probably sphinx based would be a lot better, and lay the groundwork for me useful docs.

Ambro17 commented 3 years ago

Have you seen https://pdoc3.github.io/pdoc/? It helped me get a quick first working version, and i then iterated to sphinx a few months later once i had the docs more mature. I can try to open a pr with pdoc if you agree

nat-n commented 3 years ago

@Ambro17 thanks for the offer, that might be worth a shot. Although the front page gives the impression it's more geared towards code documentation (i.e. from docstrings, rather than usage guides), which isn't so relevant at this point.

I appreciate the point about sphinx + rst being a bit inconvenient, but I think that's what I want longer term, so I'd rather stick with rst (having dealt with it so far for the readme).

So my first impression is that it's not a great fit, unless I'm missing something?

mshafer1 commented 2 years ago

@nat-n, Would you be open to a PR to add a docs folder intended to be served via github-pages? (i.e, renders with sphinx + rst and/or markdown)?

nat-n commented 2 years ago

Hi @mshafer1, thanks for the suggestion. I'd totally be open to progressing in that direction.

Sphinx with rst would be my default choice, à la ReadTheDocs. IMO rst is not much fun to work with but markdown is not expressive enough. I'm still open to other suggestions as well.

However the main obstacle is the work required to create a good document structure for the new docs website, and populate enough of it from the readme that it could functionally replace the readme as a reference, without causing confusion about how to maintain docs between the readme and the website.

So I think to realise value from this is not a trivial task, and would probably take a little bit of iteration to get right. My priority for the time I am able to dedicate to this project in the near term is to focus on fixing bugs and adding high value features. But if you're keen to contribute some effort to work on this then that's very cool.

nat-n commented 1 year ago

The new documentation website is live, thanks to @usr-ein