Sphinx Documentation

[hlship]

This PR creates an initial set of documentation using Sphinx and Restructured Text, based on a pattern I've used for Lacinia and Lacinia-Pedestal. It's very easy to get things set up on ReadTheDocs.org.

There's not a lot here ... think of this as a skeleton and head start. I also hit the limits of my knowledge with Lumo in a few places and I need to switch back to other work now.

Do set this up locally, you'll need to install Python, pip (the Python package manager) and then:

pip install recommonmark
pip install sphinx
pip install sphinx-autobuild
pip install sphinx-rtd-theme

You can edit documentation by going into the docs folder and execute make live. This will open up a browser. The browser live reloads when files change. The default RTD theme looks fine to me, and the built-in navigation (and search) is super-useful.

Get in contact if you need any extra help. I may have more time to work on documentation next week.

[anmonteiro]

@hlship Documentation is highly appreciated.

I'm ashamed to admit that I haven't looked at this yet, though. Please give me some more time, and sorry for the wait!

[arichiardi]

@hlship @anmonteiro

I was looking at this one again and it is a pity that it is still pending. Why don't we move it at least to the wiki section on GitHub so that the content is available?

I can do that in these days...then when we figure out the hosting and all we can always move it.

[hlship]

Sounds fine to me. I'm actually going to investigate https://antora.org/ which uses AsciiDoctor and a more familiar stack (the Python stack used by Sphinx is quite alien to me). Antora is about building and publishing, but not hosting, which is probably fine.

…

On Mon, Mar 26, 2018 at 2:05 PM, Andrea Richiardi ***@***.***> wrote: @hlship <https://github.com/hlship> @anmonteiro <https://github.com/anmonteiro> I was looking at this one again and it is a pity that it is still pending. Why don't we move it at least to the wiki section on GitHub so that the content is available? I can do that in these days...then when we figure out the hosting and all we can always move it. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#313 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AADNtJ4ItkyK3R5meqHY5lxl6tNbDD0iks5tiVgFgaJpZM4QipEc> .

-- Howard M. Lewis Ship Senior Mobile Developer at Walmart Labs Creator of Apache Tapestry (971) 678-5210 http://howardlewisship.com @hlship

[arichiardi]

@hlolli Thanks for your initial cut, we now have a wiki! https://github.com/anmonteiro/lumo/wiki

[arichiardi]

I must be blind but I don't think I see the roll.dice source file here, should we show it as part of the doc? I would like to add it to the wiki as well.

[hlship]

It's hypothetical ... I never even wrote it.

[arichiardi]

Got it, you actually made me try and realize that indeed tools.cli is self-host compatible :D