make an awesome homepage on RTFD.org, or at least make it useful
right now, the readthedocs site has some of the API and a presentation - not very useful. it could be our main homepage, if it would integrate the README file, for example.
this has been done in the borgbackup project to good effect.
the checklisthere sounds something like this:
-
merge the main website into the README file -
integrate the README file in the Sphinx build, probably by turning it into RST, or converting the rest of the RST files into markdown (unlikely)- this actually works directly now, thanks to RTFD's new markdown support. unfortunately, it is buggy: some things do not render correctly, because they are still treated as RST. so maybe we need to convert all those markdown files to RST. pandoc could help with a one-time conversion. -
split the README in multiple section -
expand the user guide, see the edits from #5 (closed) (usage improvements) -
document how to send mail with thunderbird, --mta
and--mua
(see #7 (closed)) -
redirect the main website to the RTFD site (this currently fails because the [[!meta redir="..."]]
plugin seems to be scrubbed away, see the documentation on the meta directive for more info)
nice to have ideas, completely optional:
-
make the RTFD site pretty, maybe using a custom theme (looked into the alabster theme but it requires a change to support arbitrary edit links)it's good enough for now -
make a screencast of monkeysign in actionsee #48 instead -
add "edit this page" links on RTFD to point here -
ship the documentation in asee #45 (closed) for this now-doc
debian package, work started in: https://0xacab.org/monkeysphere/monkeysign/tree/dev/sphinx-build
The Wiki tab here points to RTFD now, which is a little dishonest: people can't really edit it. but i didn't want the gitlab wiki to be spawned and duplicate documentation yet again, as I just managed to close down the duplication on the ikiwiki site.