move docs to RtD

[chadwhitacre]

In order to drive quality we want to use literate programming with published documentation coming from inline docstrings. The tooling for this is Sphinx w/ hosting on RTD.

[chadwhitacre]

Ideal would be to host on RTD using aspen.io as a CNAME while keeping the existing theme more or less.

[pjz]

I think the TODO here is to write the build system bits that will build the docs and put them on RTD. Which we should do ASAP; once they're in shape we can point aspen.io there via CNAME, but in the meantime it'd be a way to get feedback and see what more needs doing.

[pjz]

• Make ChangeLog easier to find per ChangeLog is hard to find #435

[chadwhitacre]

It's on me to configure RtD asap ... best to start with even broken docs up there and iterate until we can cut aspen.io over to it.

[techtonik]

RtD handles localizations badly. Basically we will need a copy of aspen repository for every language. =/ https://read-the-docs.readthedocs.org/en/latest/localization.html#project-with-multiple-translations

[pjz]

Do we have translations? Let's burn that bridge when we come to it.

[techtonik]

I don't like Sphinx + RtD. Can Aspen generate a static version of itself and host it? Something like http://simpla.io/

[pjz]

Sphinx generates nice docs from code comments, thus encouraging them both to stay up to date. RtD is a defacto (python-world) standard, and is also free. We're currently doing self-hosted docs and they tend to easily get out of date, as well as eventually costing us $$$ if we pull enough traffic to overwhelm the heroku instance that's currently hosting them.

[chadwhitacre]

@techtonik at #403:

Some kind of reference page that list all variables that set automatically in Simplates context will be useful. For example, path is a very common name in my scripts, and while it makes sense, I was a little surprised.

There seems to be these variables:

• path
• request
• response

What else?

[chadwhitacre]

Hmmm ... a start.

[chadwhitacre]

Per #357 (comment) I'm trying to get this on http://pando.aspen.io/. Seeing it, but http://pando.readthedocs.io/ isn't redirecting as I'd expect.

[chadwhitacre]

Harumph. Looks like they include rel="canonical", but don't actually redirect. :-/

[techtonik]

Oh default theme. It makes projects look boring and low valued.

[pjz]

You know what they say, @techtonik : PRs accepted!

[techtonik]

Need old theme for that.

[chadwhitacre]

PRs accepted!

The ever-sounding refrain. :-)

[chadwhitacre]

Oh default theme. It makes projects look boring and low valued.

I mean, you're right, @techtonik. I would love to have a custom theme for the projects at http://*.aspen.io/, to tie in with the homepage.