pando.py icon indicating copy to clipboard operation
pando.py copied to clipboard

Published 20 hours ago • verified publisher icon AspenWeb

move docs to RtD

Open chadwhitacre opened this issue 11 years ago • 17 comments

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 avatar May 06 '14 13:05 chadwhitacre

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

chadwhitacre avatar May 06 '14 13:05 chadwhitacre

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 avatar May 29 '14 14:05 pjz

  • [ ] Make ChangeLog easier to find per #435

pjz avatar Aug 06 '15 16:08 pjz

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.

chadwhitacre avatar Sep 03 '15 15:09 chadwhitacre

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

techtonik avatar Oct 08 '15 16:10 techtonik

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

pjz avatar Oct 08 '15 18:10 pjz

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

techtonik avatar Oct 08 '15 19:10 techtonik

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.

pjz avatar Oct 08 '15 19:10 pjz

@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 avatar Mar 08 '16 14:03 chadwhitacre

Hmmm ... a start.

screen shot 2016-09-07 at 3 52 22 pm

chadwhitacre avatar Sep 07 '16 19:09 chadwhitacre

Per https://github.com/AspenWeb/pando.py/issues/357#issuecomment-245387376 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.

screen shot 2016-09-07 at 3 53 55 pm

chadwhitacre avatar Sep 07 '16 19:09 chadwhitacre

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

screen shot 2016-09-07 at 3 58 19 pm

chadwhitacre avatar Sep 07 '16 19:09 chadwhitacre

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

techtonik avatar Sep 08 '16 05:09 techtonik

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

pjz avatar Sep 08 '16 05:09 pjz

Need old theme for that.

techtonik avatar Sep 08 '16 06:09 techtonik

PRs accepted!

The ever-sounding refrain. :-)

chadwhitacre avatar Sep 08 '16 12:09 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.

chadwhitacre avatar Sep 09 '16 02:09 chadwhitacre