Add Sphinx/RST-based documentation website

[usr-ein]

Summary

This PR splits the documentation written in README.rst into a set of RST files linked together with Table of Content directives (toc) in RST.

It also adds a logo for the project, and some CI code to have sphinx generate the HTML pages for the doc.

To manage the doc, it also adds two Poe commands:

• poe doc-generate: (Re)Generate the HTML doc using Sphinx
• poe doc-livereload: Serves the doc locally and re-generate it upon editing

I also modified poe clean to clean the generated doc folder.

While I was copy/pasting blobs from the README.rst, I also added a few examples to the pages that were a bit lacking, such as the "Composing tasks" page, and the "Installation" page.

For the Sphinx theme, I went for the well maintained furo theme which looks modern and lightweight.

Previews of the website

Documentation file structure

configuration
├── index.rst
├── project-wide_configuration.rst
└── task_level_configuration.rst
getting_started
├── basic_usage.rst
├── index.rst
└── installation.rst
tasks
├── index.rst
└── types_of_tasks
    ├── cmd.rst
    ├── expr.rst
    ├── ref.rst
    ├── script.rst
    ├── sequence.rst
    ├── shell.rst
    └── switch.rst
tutorials
├── composing_tasks.rst
├── index.rst
└── loading_tasks_from_another_file.rst

Logo

I'm not a graphic designer, but I strongly believe in the virtue of good design and packaging. Having a logo for this project seemed very important as it could incentivise more people to adopt the project and grow the community.

Since the project is named "Poe the Poet", I went with a stylised version of an Edgar Allan Poe portrait I found here and put it in a nice oval shape, which still leaves it easy on the eyes.

I'm not particularly attached to what the logo looks like, but I still think any logo would be a worthwhile addition.

Remaining implementation steps

I haven't tested the CI code introduced in this PR, but the goal is to have the CI run sphinx to build the HTML files, and then use the peaceiris/actions-gh-pages@v3 action to publish it to Github Page.

It should work, as best as I can tell, but I don't know how to test it.

Here are a few guides I think we could follow for this:

• https://coderefinery.github.io/documentation/gh_workflow/
• https://stackoverflow.com/questions/57989790/using-github-actions-to-publish-documentation

Motivation

I've been using Poe The Poet and I think it's an amazing tool that is really lacking in the Poetry ecosystem. I thought it'd be great to have a documentation website for it (as outlined in issue #11 ), as it'd probably make it a way more attractive and used tool.

[nat-n]

Wow! Thanks for the effort @usr-ein, this is fantastic.

I've been meaning to do something like this for a while, but it's hard to prioritize, relative to new features.

I actually had something similar in mind for a logo, was going to try with midjourney sometime :P . I'm a little concerned about copyright for lifting something off another website like this, though I see someone selling prints of the same image on ebay so it's probably OK for now.

I'm going to take some time to review (and probably tweak) the content, look into the failing tests, and then we can merge this to main to get it published. If you're keen it should be possible to run the github workflows on your own fork of the repo.

[nat-n]

I made some tweaks to the setup, and published it here http://poethepoet.natn.io/ :)

I'll continue to review and touch up the docs for a bit for making it official.

[usr-ein]

Thanks for the review! It's great to see you're actively maintaining this repo!

I see you've made very good changes and it all integrates more smoothly now.
Lmk if there's anything that need adding on this PR and that I can help you with!

[nat-n]

I've touched up the docs and readme to the point where I'm reasonably happy with the standard.

Thanks again @usr-ein for setting this up, and giving me the push to work on it as well :)