Move process/development/etc docs to static site #419

Closed
bitprophet opened this Issue Aug 22, 2011 · 50 comments

Comments

Projects
None yet
3 participants
@bitprophet
Member

bitprophet commented Aug 22, 2011

Most of the development and index pages of the current docs would work better as a dedicated static site, where changes can be made without having to copy them to each release branch, etc.

This will also be a good excuse to rearrange a little bit.

Specifically, move these to the new site:

  • Everything in index.rst which is not the Documentation section -- so the intro/about, installation, development, and getting help sections
  • The Installation and Development pages themselves
    • Installation is slightly more tied to the code itself than the rest, so it's a maybe -- e.g. we occasionally get patches that add to the install docs (such as the PyPM chunk).
  • Split out the Releases & Support of older releases sections from Development into their own page -- that info is both user and dev related.
  • Probably split existing intro material into front-page and "about the project" content...
  • ...so we can add more to the front-page, such as:
    • Latest stable versions & link to their changelogs
    • Up-front-and-personal links to various things ("Need help? ", "Want to download? ", "Want to contribute? " etc)

This would then leave the in-code docs covering:

  • Some sort of basic intro, probably pointing to the main site
  • The notes about the docs themselves
  • Tutorial
  • Usage docs
  • FAQ
  • API docs
  • Changelog

Finally, add this entirely new content to the new site:

  • Blog for announcements/releases - and then ML posts become links here
  • Roadmap page that gets updated periodically with what's ahead
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Sep 29, 2013

Member

Poking at this now, also with an eye for a similar setup for Paramiko and others (Invoke etc).

Feel like there are two minimal-effort ways to go for a static site that integrates with Sphinx API docs:

Plus of Octopress site is that it has a blog engine built in, which gives me a useful non-ML/non-Twitter announcement channel, and lets me move that crap off my personal blog where few people will think to look. Minus is that it would be difficult to meaningfully visually distinguish such sites from my personal blog - there's almost no color on it to change, for example.

Plus of Sphinx site is that it'd visually/navigationally integrate better with the API docs on RTD (especially if I were to use the same theme on both parts), and the Kr theme gives slightly more visual room to elements I could change up (name/logo, fonts are heavier so link color changes will stand out more etc). Minus is inverse of Octopress - no useful blog/stream.


Alternately, I could try using Git submodules or some other Sphinx import hook (e.g. an 'extension' that simply pulls in content?) to continue hosting everything at RTD, but split out the static content into a separate repo.

Benefit of that is I gain the "keep things that are not version related out of the versioned code repo" angle of a static site, but there's no need to try and bridge two different installations/themes/tools. Downside is, like option 2 above, there's still no blog.

Member

bitprophet commented Sep 29, 2013

Poking at this now, also with an eye for a similar setup for Paramiko and others (Invoke etc).

Feel like there are two minimal-effort ways to go for a static site that integrates with Sphinx API docs:

Plus of Octopress site is that it has a blog engine built in, which gives me a useful non-ML/non-Twitter announcement channel, and lets me move that crap off my personal blog where few people will think to look. Minus is that it would be difficult to meaningfully visually distinguish such sites from my personal blog - there's almost no color on it to change, for example.

Plus of Sphinx site is that it'd visually/navigationally integrate better with the API docs on RTD (especially if I were to use the same theme on both parts), and the Kr theme gives slightly more visual room to elements I could change up (name/logo, fonts are heavier so link color changes will stand out more etc). Minus is inverse of Octopress - no useful blog/stream.


Alternately, I could try using Git submodules or some other Sphinx import hook (e.g. an 'extension' that simply pulls in content?) to continue hosting everything at RTD, but split out the static content into a separate repo.

Benefit of that is I gain the "keep things that are not version related out of the versioned code repo" angle of a static site, but there's no need to try and bridge two different installations/themes/tools. Downside is, like option 2 above, there's still no blog.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Sep 29, 2013

Member

Looks like Tinkerer is effectively a Sphinx extension that does blogging - could work well for what I want, or at least serve as a base to hack on.

Given all I really want is "bloglike" behavior for a subsection of the site, that feels like the best compromise. Will poke.

Member

bitprophet commented Sep 29, 2013

Looks like Tinkerer is effectively a Sphinx extension that does blogging - could work well for what I want, or at least serve as a base to hack on.

Given all I really want is "bloglike" behavior for a subsection of the site, that feels like the best compromise. Will poke.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Sep 29, 2013

Member

Wrote this: http://bitprophet.org/blog/2013/09/29/project-website-musings/

tl;dr probably gonna try the '2x sphinx, w/ the static repo using Tinkerer for blog section' approach.

Member

bitprophet commented Sep 29, 2013

Wrote this: http://bitprophet.org/blog/2013/09/29/project-website-musings/

tl;dr probably gonna try the '2x sphinx, w/ the static repo using Tinkerer for blog section' approach.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 4, 2013

Member

Poking at Tinkerer now, it's pretty opinionated and wants to "own" the entire Sphinx site - need to dig further but not sure it'd be easy to try and shoehorn it into a subsection of a "regular" Sphinx setup.

Then again since it's designed to have non-post 'pages' and that fits the overall UX/IA of these small static sites - it's probably easiest to just let Tinkerer drive things after all & make a custom theme on top of it to match the API site.

Member

bitprophet commented Dec 4, 2013

Poking at Tinkerer now, it's pretty opinionated and wants to "own" the entire Sphinx site - need to dig further but not sure it'd be easy to try and shoehorn it into a subsection of a "regular" Sphinx setup.

Then again since it's designed to have non-post 'pages' and that fits the overall UX/IA of these small static sites - it's probably easiest to just let Tinkerer drive things after all & make a custom theme on top of it to match the API site.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 4, 2013

Member

N.B. poking at paramiko.org for this - once happy with the approach re: how that site works, will then apply same to Fabric.

A fully Tinkerer driven site differs from a traditional Sphinx one (at least re: how I make them, with the repo root being the Sphinx source dir and _build/html being the output dir) like so:

  • Blog posts go into top level year-based folders (and then a month/day hierarchy), pages go into a top level pages/ folder. No other top level .rst files exist besides the Tinkerer-managed master.rst (see below.)
  • These files need to be created via tinker --(page|post), though they're simple enough - live in the above locations, contain some metadata directives at page bottom, and get added to master.rst below.
  • Tinkerer manages a master.rst which holds the top level toctree directive, as per its internals docs.
  • It builds into blog/html and puts .doctree files into blog/doctrees (I've never run into these before, not sure what they are offhand; they're binary.)
    • EDIT: this is generated by sphinx -d <path> but apparently it's effectively default behavior (e.g. in Fab's docs there's a _build/doctrees folder alongside _build/html - I just never look in there.)

Things I would want to change if I was to go this route:

  • Figure out if I can change what the index page "is" - right now it is another custom-generated HTML page containing the blog homepage, and is called "Home" in the nav.
    • I'd want it to be called Blog and live at /blog/ or /blog.html, and use one of my custom pages as the root.
  • Theme it to look like e.g. the Kr theme - unclear how its page structure maps to "normal" Sphinx sites, would have to compare DOMs. All its builtin themes are fugly.
  • Update its sidebar to include the desired links to the sister API site (as per the overall approach I am taking here) - seems like I can write a simple extension for that or just update the templates.
  • Blog archive is only linked from that home/index page, might be nice to have it linked on any blog page in the sidebar or footer. Also possibly doable just by tweaking the templates.
Member

bitprophet commented Dec 4, 2013

N.B. poking at paramiko.org for this - once happy with the approach re: how that site works, will then apply same to Fabric.

A fully Tinkerer driven site differs from a traditional Sphinx one (at least re: how I make them, with the repo root being the Sphinx source dir and _build/html being the output dir) like so:

  • Blog posts go into top level year-based folders (and then a month/day hierarchy), pages go into a top level pages/ folder. No other top level .rst files exist besides the Tinkerer-managed master.rst (see below.)
  • These files need to be created via tinker --(page|post), though they're simple enough - live in the above locations, contain some metadata directives at page bottom, and get added to master.rst below.
  • Tinkerer manages a master.rst which holds the top level toctree directive, as per its internals docs.
  • It builds into blog/html and puts .doctree files into blog/doctrees (I've never run into these before, not sure what they are offhand; they're binary.)
    • EDIT: this is generated by sphinx -d <path> but apparently it's effectively default behavior (e.g. in Fab's docs there's a _build/doctrees folder alongside _build/html - I just never look in there.)

Things I would want to change if I was to go this route:

  • Figure out if I can change what the index page "is" - right now it is another custom-generated HTML page containing the blog homepage, and is called "Home" in the nav.
    • I'd want it to be called Blog and live at /blog/ or /blog.html, and use one of my custom pages as the root.
  • Theme it to look like e.g. the Kr theme - unclear how its page structure maps to "normal" Sphinx sites, would have to compare DOMs. All its builtin themes are fugly.
  • Update its sidebar to include the desired links to the sister API site (as per the overall approach I am taking here) - seems like I can write a simple extension for that or just update the templates.
  • Blog archive is only linked from that home/index page, might be nice to have it linked on any blog page in the sidebar or footer. Also possibly doable just by tweaking the templates.
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 4, 2013

Member

Seems Tinkerer hardcodes the first page of blog pagination as being pagename = 'index' (which is then yielded up a chain until it ends up hitting the builtin Sphinx html-collect-pages event). This is done in ext/aggregator.py in make_aggregated_pages, which is called in ext/blog.py in collect_additional_pages, which is in turn called in html_collect_pages, which is linked to that html-collect-pages event (Sphinx docs).

So I can't easily change this without hacking up the blog/aggregator 'extension' files above :( Would need to copy/paste/modify at least one or two large functions (they're not set up for extensibility.)

Member

bitprophet commented Dec 4, 2013

Seems Tinkerer hardcodes the first page of blog pagination as being pagename = 'index' (which is then yielded up a chain until it ends up hitting the builtin Sphinx html-collect-pages event). This is done in ext/aggregator.py in make_aggregated_pages, which is called in ext/blog.py in collect_additional_pages, which is in turn called in html_collect_pages, which is linked to that html-collect-pages event (Sphinx docs).

So I can't easily change this without hacking up the blog/aggregator 'extension' files above :( Would need to copy/paste/modify at least one or two large functions (they're not set up for extensibility.)

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 4, 2013

Member

Turning this around, what's the minimum we want in a blog?

  • RSS or Atom feed, so folks can follow/get news
    • A sorted-by-date page (given RSS feeds require ability to do so) could logically follow
    • Which wants pagination, at least eventually.
  • Ability to link to individual posts, so we can reference news updates on twitter/irc/etc
  • Don't care as much about tags/categories since it's a very focused "blog".

So, possibly reusing chunks of Tinkerer if they make sense, could do:

  • Store blog posts in blog/<post name>.rst
  • Metadata directive(s) in those files w/ date, maybe tag/category later if desired
    • See if can reuse Tinkerer for this bit
  • Extension that hooks into build step, generates the RSS and display page also in the blog/ hierarchy
    • Ditto here, at least for RSS - as above the aggregator page stuff may be too opinionated

So tl;dr a much more lightweight, add-to-your-Sphinx-site version of Tinkerer. Yay, another project :(

Member

bitprophet commented Dec 4, 2013

Turning this around, what's the minimum we want in a blog?

  • RSS or Atom feed, so folks can follow/get news
    • A sorted-by-date page (given RSS feeds require ability to do so) could logically follow
    • Which wants pagination, at least eventually.
  • Ability to link to individual posts, so we can reference news updates on twitter/irc/etc
  • Don't care as much about tags/categories since it's a very focused "blog".

So, possibly reusing chunks of Tinkerer if they make sense, could do:

  • Store blog posts in blog/<post name>.rst
  • Metadata directive(s) in those files w/ date, maybe tag/category later if desired
    • See if can reuse Tinkerer for this bit
  • Extension that hooks into build step, generates the RSS and display page also in the blog/ hierarchy
    • Ditto here, at least for RSS - as above the aggregator page stuff may be too opinionated

So tl;dr a much more lightweight, add-to-your-Sphinx-site version of Tinkerer. Yay, another project :(

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 6, 2013

Member

Have a custom blog extension working for the basics outline above, sans RSS (but since the collection, display & sorting of the blog posts is all implemented, RSS should come easily.) Also sans opening-paragraph display.

Only downside is that the listing (and I reckon RSS will go the same way) is outputted via a regular directive/node within a document, meaning pagination would need to be done by hand or (as it's set up now) simply doesn't happen. Can solve that later - as long as the "first" landing page + the per-post pages do not change URL structure, it should be backwards compatible enough to prevent link rot.

Member

bitprophet commented Dec 6, 2013

Have a custom blog extension working for the basics outline above, sans RSS (but since the collection, display & sorting of the blog posts is all implemented, RSS should come easily.) Also sans opening-paragraph display.

Only downside is that the listing (and I reckon RSS will go the same way) is outputted via a regular directive/node within a document, meaning pagination would need to be done by hand or (as it's set up now) simply doesn't happen. Can solve that later - as long as the "first" landing page + the per-post pages do not change URL structure, it should be backwards compatible enough to prevent link rot.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 6, 2013

Member

Opening paragraph done, RSS done. Time to tie everything together and get theming.

Member

bitprophet commented Dec 6, 2013

Opening paragraph done, RSS done. Time to tie everything together and get theming.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 9, 2013

Member

Working on a custom variant of Kr/Sphinx theme, see e.g. sphinx-theme #1

Member

bitprophet commented Dec 9, 2013

Working on a custom variant of Kr/Sphinx theme, see e.g. sphinx-theme #1

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 10, 2013

Member

Have that in reasonably good shape now, back to Paramiko/Fabric static-site specific "how do I want these things organized" stuff. Which may drive more changes to sphinx-theme as needed.

Member

bitprophet commented Dec 10, 2013

Have that in reasonably good shape now, back to Paramiko/Fabric static-site specific "how do I want these things organized" stuff. Which may drive more changes to sphinx-theme as needed.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 13, 2013

Member

Next up for this site junk is tying them together:

  • Ideally some way to share color schemes, having to maintain that 2x could lead to subtle/jarring differences anytime something forgets to copy over. However that's all done via conf.py, so it'd need to be something dumb like publishing the colorscheme to pypi and importing it (?).
    • Alternately, have the theme ship with colorschemes to be selected from (though that hurts differentiation.)
    • Or put more work into Alabaster #5 such that there are only a bare handful of base colors specified and the theme does the rest of the work. Keeping, say, 3 color settings around is much less error-prone than e.g. 15.
  • Ditto re: other settings, actually - logo image, description blurb, etc. So maybe partial conf.py sharing (+ image file, + etc) is inevitable.
  • Navigation: the sidebars should allow the sides to cross-link. Whether this should result in identical nav on both sites, or not, is up in the air.
  • Sphinx intersite linking would be nice too.
Member

bitprophet commented Dec 13, 2013

Next up for this site junk is tying them together:

  • Ideally some way to share color schemes, having to maintain that 2x could lead to subtle/jarring differences anytime something forgets to copy over. However that's all done via conf.py, so it'd need to be something dumb like publishing the colorscheme to pypi and importing it (?).
    • Alternately, have the theme ship with colorschemes to be selected from (though that hurts differentiation.)
    • Or put more work into Alabaster #5 such that there are only a bare handful of base colors specified and the theme does the rest of the work. Keeping, say, 3 color settings around is much less error-prone than e.g. 15.
  • Ditto re: other settings, actually - logo image, description blurb, etc. So maybe partial conf.py sharing (+ image file, + etc) is inevitable.
  • Navigation: the sidebars should allow the sides to cross-link. Whether this should result in identical nav on both sites, or not, is up in the air.
  • Sphinx intersite linking would be nice too.
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 23, 2013

Member

Re: where changelogs live:

  • Releases can be used anywhere, so that's no problem
  • Having them in the API codebase originally made sense due to linking to API/usage docs
  • However this means we still have the "in many places, with inconsistent contents" problem.
  • Moving the changelog to the static site has its own problems, however:
    • All doc links would require Intersphinx support/semantics, and that's if it's even possible to Intersphinx to autodoc targets (eg Python domain stuff) and not just refs/docs.
    • More worryingly - users could no longer submit pull requests containing changelog updates, or at absolute best would need to fork the static site and all PRs would really be 2x PRs (code, site). That's pretty bad.

I started writing this thinking "yea, changelogs should be in the static site" but then I thought of the 2nd counterpoint above. I'd rather continue having multiple changelogs (especially ones that tend to only differ via additives, given how they merge currently) than require users to submit PRs to two repos. So...never mind.


On the other hand - now that Releases is in use, older changelogs can have misleading info still. To wit:

  • 1.7 is no longer the latest release, so its changelog is always topped off by 1.7.x bugfix releases on.
  • Backported feature/support tickets intended for it, also appear in the changelog, and do correctly show up in those bugfix releases.
  • HOWEVER because those issue types are also intended for the upcoming feature release, they are left in the 'feature' bucket...and then appear in "Next feature release" forever.
    • In newer changelogs where a feature release occurs after these backports, it's not an issue.

So that behavior kind of wants a single changelog, but still not bad enough to be worth 2x repos. (Maybe move the static site repo into the main repo but build them separately? Worth thought.)

Other possible fixes to the above:

  • Change behavior of 'backported' so it's solely a "you get moved into bugfix land" flag. Tempting...
  • Just filter them out when displaying 'Next feature release' (but they would still show up in the next feature release...). Eh.
Member

bitprophet commented Dec 23, 2013

Re: where changelogs live:

  • Releases can be used anywhere, so that's no problem
  • Having them in the API codebase originally made sense due to linking to API/usage docs
  • However this means we still have the "in many places, with inconsistent contents" problem.
  • Moving the changelog to the static site has its own problems, however:
    • All doc links would require Intersphinx support/semantics, and that's if it's even possible to Intersphinx to autodoc targets (eg Python domain stuff) and not just refs/docs.
    • More worryingly - users could no longer submit pull requests containing changelog updates, or at absolute best would need to fork the static site and all PRs would really be 2x PRs (code, site). That's pretty bad.

I started writing this thinking "yea, changelogs should be in the static site" but then I thought of the 2nd counterpoint above. I'd rather continue having multiple changelogs (especially ones that tend to only differ via additives, given how they merge currently) than require users to submit PRs to two repos. So...never mind.


On the other hand - now that Releases is in use, older changelogs can have misleading info still. To wit:

  • 1.7 is no longer the latest release, so its changelog is always topped off by 1.7.x bugfix releases on.
  • Backported feature/support tickets intended for it, also appear in the changelog, and do correctly show up in those bugfix releases.
  • HOWEVER because those issue types are also intended for the upcoming feature release, they are left in the 'feature' bucket...and then appear in "Next feature release" forever.
    • In newer changelogs where a feature release occurs after these backports, it's not an issue.

So that behavior kind of wants a single changelog, but still not bad enough to be worth 2x repos. (Maybe move the static site repo into the main repo but build them separately? Worth thought.)

Other possible fixes to the above:

  • Change behavior of 'backported' so it's solely a "you get moved into bugfix land" flag. Tempting...
  • Just filter them out when displaying 'Next feature release' (but they would still show up in the next feature release...). Eh.
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Dec 25, 2013

Member

ALso, already seeing real world examples of exactly what I fear - folks looking at the 1.8 changelog and not seeing the 'unreleased feature' stuff from master (because 1.8 branch doesn't know about them!) Definitely worth seeing if 'one repo, two doc trees built separately' is possible.

Hopefully just tell RTD to look in /docs/ explicitly, and have the build process for the static site look at e.g. /site/.

Member

bitprophet commented Dec 25, 2013

ALso, already seeing real world examples of exactly what I fear - folks looking at the 1.8 changelog and not seeing the 'unreleased feature' stuff from master (because 1.8 branch doesn't know about them!) Definitely worth seeing if 'one repo, two doc trees built separately' is possible.

Hopefully just tell RTD to look in /docs/ explicitly, and have the build process for the static site look at e.g. /site/.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 5, 2014

Member

In fact I just checked and RTD does let you build a project with a single version, aka no /en/<version>/ (tho the little RTD badge still appears in the sidebar by default - w/ a custom theme, probably not an issue.) Tested it out for contribution-guide.org and it works!

So the single-repo approach actually looks feasible now. Will try it out in a branch w/ paramiko + .org.

Member

bitprophet commented Jan 5, 2014

In fact I just checked and RTD does let you build a project with a single version, aka no /en/<version>/ (tho the little RTD badge still appears in the sidebar by default - w/ a custom theme, probably not an issue.) Tested it out for contribution-guide.org and it works!

So the single-repo approach actually looks feasible now. Will try it out in a branch w/ paramiko + .org.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 22, 2014

Member

Next up for Paramiko's in progress version of this setup:

  • Migrate NEWS -> sites/www/changelog.rst
    • Make sure links to API docs work using intersphinx or something - requires porting at least some API docs to Sphinx :D
  • Think about making the 'index' page (either actual index.rst, or the conf.py setting targeting a different file) in the 'docs' tree not look like a landing/index page?
    • No 'Welcome' header, etc; as if it was always only reachable as "part of" the www site.
    • Requires poking at the unified sidebar idea.
Member

bitprophet commented Jan 22, 2014

Next up for Paramiko's in progress version of this setup:

  • Migrate NEWS -> sites/www/changelog.rst
    • Make sure links to API docs work using intersphinx or something - requires porting at least some API docs to Sphinx :D
  • Think about making the 'index' page (either actual index.rst, or the conf.py setting targeting a different file) in the 'docs' tree not look like a landing/index page?
    • No 'Welcome' header, etc; as if it was always only reachable as "part of" the www site.
    • Requires poking at the unified sidebar idea.
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 23, 2014

Member

Intersphinx, from perspective of a changelog or other www-site file referencing stuff in the docs/api site:

  • Lets you specify a (target path/URI for building links, path/URI to inventory file) tuple in intersphinx_mapping
  • Problem is that I want that first part to be different when I build docs locally, versus when they build on RTD.
    • Locally, I want it to be a local relative path from www's source to docs' source.
    • Publicly/RTD-wise, I want it to be an absolute URI to eg docs.myproject.com
  • You can override settings at build time with -D key=value but that almost definitely only works for "simple" scalar settings.
    • And since conf.py's aren't evaluated lazily there's no way to e.g. tickle a base variable and refer to it within intersphinx_mapping
  • Only other method I can see to effect this is to use distinct conf.py files for local vs RTD - but assuming RTD lets us do this (99% sure) it should work out OK.
Member

bitprophet commented Jan 23, 2014

Intersphinx, from perspective of a changelog or other www-site file referencing stuff in the docs/api site:

  • Lets you specify a (target path/URI for building links, path/URI to inventory file) tuple in intersphinx_mapping
  • Problem is that I want that first part to be different when I build docs locally, versus when they build on RTD.
    • Locally, I want it to be a local relative path from www's source to docs' source.
    • Publicly/RTD-wise, I want it to be an absolute URI to eg docs.myproject.com
  • You can override settings at build time with -D key=value but that almost definitely only works for "simple" scalar settings.
    • And since conf.py's aren't evaluated lazily there's no way to e.g. tickle a base variable and refer to it within intersphinx_mapping
  • Only other method I can see to effect this is to use distinct conf.py files for local vs RTD - but assuming RTD lets us do this (99% sure) it should work out OK.
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 23, 2014

Member

Yup RTD has a slot for conf.py location, so I should be able to get away with more import-based shenanigans. Set up a "Paramiko (WWW)" project on RTD to get this started testing as well

EDIT: Spoke too soon, RTD seems to have a bug preventing it from switching Git branches. Trying to work around for now so I don't have to troubleshoot this via master.

EDIT 2: Can work around git issue by just making a different Version entry, but then run into this issue. Can prob work around that by just being stupid and using rtd/conf.py instead of rtd_conf.py. Hurr.

EDIT 3: And now RTD is assuming my doctree root / master doc (e.g. index.rst) is next to the conf.py. Hrrgh.

EDIT 4: Yup, same thing actually, Project.conf_dir in RTD implicitly assumes my conf.py is at the root of my docs directory. Time for a new approach - I think RTD sets env flags I can test in my conf.py, so perhaps I can make that the differentiator re: intersphinx.

Member

bitprophet commented Jan 23, 2014

Yup RTD has a slot for conf.py location, so I should be able to get away with more import-based shenanigans. Set up a "Paramiko (WWW)" project on RTD to get this started testing as well

EDIT: Spoke too soon, RTD seems to have a bug preventing it from switching Git branches. Trying to work around for now so I don't have to troubleshoot this via master.

EDIT 2: Can work around git issue by just making a different Version entry, but then run into this issue. Can prob work around that by just being stupid and using rtd/conf.py instead of rtd_conf.py. Hurr.

EDIT 3: And now RTD is assuming my doctree root / master doc (e.g. index.rst) is next to the conf.py. Hrrgh.

EDIT 4: Yup, same thing actually, Project.conf_dir in RTD implicitly assumes my conf.py is at the root of my docs directory. Time for a new approach - I think RTD sets env flags I can test in my conf.py, so perhaps I can make that the differentiator re: intersphinx.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 23, 2014

Member

Well that was a fun half day. Turns out I was really stupid for forgetting the READTHEDOCS env var trick, as that let me work around all of the edge case bugs I ran into w/ RTD & conf file location crap.

Now have a working setup where local builds of one doc site can reference the other, and same for public. Would be easy to extend it for reciprocal intersphinxing, but for now that's not even necessary (the www sites for projects are unlikely to contain material linked to from the API/usage docs.)

Member

bitprophet commented Jan 23, 2014

Well that was a fun half day. Turns out I was really stupid for forgetting the READTHEDOCS env var trick, as that let me work around all of the edge case bugs I ran into w/ RTD & conf file location crap.

Now have a working setup where local builds of one doc site can reference the other, and same for public. Would be easy to extend it for reciprocal intersphinxing, but for now that's not even necessary (the www sites for projects are unlikely to contain material linked to from the API/usage docs.)

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 24, 2014

Member

On to navigation stuff (both general and attempting to unify the 2 sites):

  • By default my newish, based-on-Kr alabaster theme setup (as installed for paramiko) has no nav sidebar.
  • Eg requests' site uses the default, packaged with Sphinx 'localtoc.html' sidebar item for navigation
    • That template uses a builtin 'toc' template variable defined here which is just the local page's ToC.
    • So, useful, but not a sitewide nav.
  • RTD's old theme (as seen in Fabric's current docs) doesn't actually override this by default, so it's the same information: local page ToC only.
  • RTD's new theme (here) uses the toctree template function instead (w/ fallback, if somehow not defined, to local ToC.)
    • This is the sitewide table of contents (with, AFAICT, some js/css to perform expandos & highlighting of current page) which is more useful for nav, but can present its own challenges (at least, I recall this from applying it to eg Invoke or Fabric's existing, old-RTD-theme oriented doctrees.)

Concerns specific to this new split-doctree world:

  • We probably want to use toctree, perhaps with different options than what RTD's new theme is using - explore this space, figure out why it was upsetting to use w/ Invoke's docs, figure out whether our doc organization should change to suit toctree or vice versa.
  • We need to marry that with a "global" navigation element, likely a second sidebar template/chunk, that links to the alternate site (ideally detecting which one it is currently "in" and highlighting it.)
    • Even better would be knowing about a few of the most interesting top level pages of the sister site and presenting those as well. E.g. when viewing an API page, it'd be rad to have a direct sidebar link to "how do I contribute [changes to what I am looking at]?"
    • Truly ideal would be a sidebar that combines both, but I don't see how this is possible without obtaining a toctree from the sister site.
      • Worth poking at intersphinx to see if that data inventory file junk includes this kind of info. Guessing not, but.
Member

bitprophet commented Jan 24, 2014

On to navigation stuff (both general and attempting to unify the 2 sites):

  • By default my newish, based-on-Kr alabaster theme setup (as installed for paramiko) has no nav sidebar.
  • Eg requests' site uses the default, packaged with Sphinx 'localtoc.html' sidebar item for navigation
    • That template uses a builtin 'toc' template variable defined here which is just the local page's ToC.
    • So, useful, but not a sitewide nav.
  • RTD's old theme (as seen in Fabric's current docs) doesn't actually override this by default, so it's the same information: local page ToC only.
  • RTD's new theme (here) uses the toctree template function instead (w/ fallback, if somehow not defined, to local ToC.)
    • This is the sitewide table of contents (with, AFAICT, some js/css to perform expandos & highlighting of current page) which is more useful for nav, but can present its own challenges (at least, I recall this from applying it to eg Invoke or Fabric's existing, old-RTD-theme oriented doctrees.)

Concerns specific to this new split-doctree world:

  • We probably want to use toctree, perhaps with different options than what RTD's new theme is using - explore this space, figure out why it was upsetting to use w/ Invoke's docs, figure out whether our doc organization should change to suit toctree or vice versa.
  • We need to marry that with a "global" navigation element, likely a second sidebar template/chunk, that links to the alternate site (ideally detecting which one it is currently "in" and highlighting it.)
    • Even better would be knowing about a few of the most interesting top level pages of the sister site and presenting those as well. E.g. when viewing an API page, it'd be rad to have a direct sidebar link to "how do I contribute [changes to what I am looking at]?"
    • Truly ideal would be a sidebar that combines both, but I don't see how this is possible without obtaining a toctree from the sister site.
      • Worth poking at intersphinx to see if that data inventory file junk includes this kind of info. Guessing not, but.
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 25, 2014

Member

Sadly Intersphinx inventory files only seem to track specifically targeted references, i.e. .. _mytarget: and autodoc stuff. No documents, no implicit header targets, etc.

So my hope to "pull in all 'document' like targets from the other site and stick in nav" isn't going to fly.

Dunno if I can do something super dumb like straight up generate a new toctree object from the other site, or if I have to go full manual and just assume the top level pages for both sites won't change often. Or just link to the other site w/ one link and not worry about trying to show a unified nav.

Member

bitprophet commented Jan 25, 2014

Sadly Intersphinx inventory files only seem to track specifically targeted references, i.e. .. _mytarget: and autodoc stuff. No documents, no implicit header targets, etc.

So my hope to "pull in all 'document' like targets from the other site and stick in nav" isn't going to fly.

Dunno if I can do something super dumb like straight up generate a new toctree object from the other site, or if I have to go full manual and just assume the top level pages for both sites won't change often. Or just link to the other site w/ one link and not worry about trying to show a unified nav.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 27, 2014

Member
  • Don't bother with more overengineered BS at this point; it can wait until later. Anything put up now is better than the current bounce-to-API (for Paramiko specifically)
  • Remove the temp Fab logo image and add an option re: plaintext "logo" horiz align (may look better non centered)
  • Possibly just have the www site sidebar link directly to the existing docs subdomain & say "API docs"
    • Alternately, have it link to the 'real' docs site & have that just be a single page placeholder linking to the Epydoc version (would require domain jiggering so maybe not worth it ATM)
  • Temporarily remove the blog from rendering until it's more finished
  • Poke around for anything else, then move back to Paramiko #178 for actual launch.
Member

bitprophet commented Jan 27, 2014

  • Don't bother with more overengineered BS at this point; it can wait until later. Anything put up now is better than the current bounce-to-API (for Paramiko specifically)
  • Remove the temp Fab logo image and add an option re: plaintext "logo" horiz align (may look better non centered)
  • Possibly just have the www site sidebar link directly to the existing docs subdomain & say "API docs"
    • Alternately, have it link to the 'real' docs site & have that just be a single page placeholder linking to the Epydoc version (would require domain jiggering so maybe not worth it ATM)
  • Temporarily remove the blog from rendering until it's more finished
  • Poke around for anything else, then move back to Paramiko #178 for actual launch.
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 28, 2014

Member

Poking at nav stuff, again trying to keep things quick n dirty to get things moving wrt Paramiko:

  • Sphinx ships with both a localtoc and globaltoc sidebar template
  • Both of them are tiny, just an h3 w/ a link to the master doc (pointless given our logo area) and outputting toc or toctree() respectively.
    • And localtoc.html wraps its content in {% if display_toc %} which is a builtin variable set by the HTML builder depending on whether the current document even has a ToC to display.
  • So we can just make our own nav sidebar, display it on all pages (hopefully there's a way to tell if we're on the index page in case we want to disable it there - but maybe not even then?) and combine the local site/page nav with a static 'remote' nav to the sister site.
    • Ideal would be to merge the index page & the sister doc link(s) into the rendered ToC but that looks difficult/impossible, so we'll have to stick them in around instead.
    • Could leave off index page link and rely on logo link, though that feels slightly messy to me. Puntable.
Member

bitprophet commented Jan 28, 2014

Poking at nav stuff, again trying to keep things quick n dirty to get things moving wrt Paramiko:

  • Sphinx ships with both a localtoc and globaltoc sidebar template
  • Both of them are tiny, just an h3 w/ a link to the master doc (pointless given our logo area) and outputting toc or toctree() respectively.
    • And localtoc.html wraps its content in {% if display_toc %} which is a builtin variable set by the HTML builder depending on whether the current document even has a ToC to display.
  • So we can just make our own nav sidebar, display it on all pages (hopefully there's a way to tell if we're on the index page in case we want to disable it there - but maybe not even then?) and combine the local site/page nav with a static 'remote' nav to the sister site.
    • Ideal would be to merge the index page & the sister doc link(s) into the rendered ToC but that looks difficult/impossible, so we'll have to stick them in around instead.
    • Could leave off index page link and rely on logo link, though that feels slightly messy to me. Puntable.
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Jan 28, 2014

Member

Went with an in-alabaster nav that can accept settings for external links. Works well enough for now. Also a bunch of style updates so the nav/toc is a bit bigger/nicer/etc.

Shutting up in here & moving to the Paramiko ticket for specifics. But this approach seems to work pretty well now so I'm totally trying it for Fabric next!

Member

bitprophet commented Jan 28, 2014

Went with an in-alabaster nav that can accept settings for external links. Works well enough for now. Also a bunch of style updates so the nav/toc is a bit bigger/nicer/etc.

Shutting up in here & moving to the Paramiko ticket for specifics. But this approach seems to work pretty well now so I'm totally trying it for Fabric next!

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 1, 2014

Member

Applying this to Fabric now:

  • Clone Paramiko's sites tree, re: shared conf/static, individual site dirs + conf.py files, and the WWW content (since Fabric's will be similarish.)
  • Modify all conf files to be appropriate for Fab
  • Transplant WWW-appropriate content from current Fab docs into WWW site (using ticket desc as guide)
  • Move rest of current Fab docs into docs/api site (tweak landing/index page, ToCs etc)
  • Ensure sister-site links are updated
  • Verify LnF (make logo appear; make sure any non grayscale colors are distinct from paramiko.org's (should already be so, removed the link overrides from the copy of Paramiko's shared_conf.py)
Member

bitprophet commented Apr 1, 2014

Applying this to Fabric now:

  • Clone Paramiko's sites tree, re: shared conf/static, individual site dirs + conf.py files, and the WWW content (since Fabric's will be similarish.)
  • Modify all conf files to be appropriate for Fab
  • Transplant WWW-appropriate content from current Fab docs into WWW site (using ticket desc as guide)
  • Move rest of current Fab docs into docs/api site (tweak landing/index page, ToCs etc)
  • Ensure sister-site links are updated
  • Verify LnF (make logo appear; make sure any non grayscale colors are distinct from paramiko.org's (should already be so, removed the link overrides from the copy of Paramiko's shared_conf.py)
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 6, 2014

Member

In lieu of rewriting nearly everything, these are changes that should get applied once the above is done (but sooner, not later):

  • Add explicit links to Paramiko's install docs on the install page - don't actually see any. If there are any, they are not enough.
  • Remove the Paramiko specific stuff (e.g. PyCrypto sections) since that's on Paramiko's site now. Thought I already did this but maybe not?
  • Replace some/all of the Development page with a link to contribution-guide
  • If applicable, remove some Troubleshooting and link to contribution-guide no overlap, not quite generic enough to port over just yet
  • Consider migrating the FAQ page to the docs site (and ditto for Paramiko perhaps?) punting for now
Member

bitprophet commented Apr 6, 2014

In lieu of rewriting nearly everything, these are changes that should get applied once the above is done (but sooner, not later):

  • Add explicit links to Paramiko's install docs on the install page - don't actually see any. If there are any, they are not enough.
  • Remove the Paramiko specific stuff (e.g. PyCrypto sections) since that's on Paramiko's site now. Thought I already did this but maybe not?
  • Replace some/all of the Development page with a link to contribution-guide
  • If applicable, remove some Troubleshooting and link to contribution-guide no overlap, not quite generic enough to port over just yet
  • Consider migrating the FAQ page to the docs site (and ditto for Paramiko perhaps?) punting for now
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 7, 2014

Member

Turns out Paramiko's link colors were actually appropriate for the Fabric "livery". Will probably just remove them from Paramiko so it uses the theme default for now.

Member

bitprophet commented Apr 7, 2014

Turns out Paramiko's link colors were actually appropriate for the Fabric "livery". Will probably just remove them from Paramiko so it uses the theme default for now.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 7, 2014

Member

Realized that the new "docs" site will need to continue showing the current (and soon, "old") versions of the all-in-one site. No real way to avoid this unfortunately - cannot in good conscience remove that info from the Web so we'll just have to deal.

Does mean that I will need to be careful about RTD sites - if I make two new ones as I was planning, I'll have to go through and recheck all the build boxes for all currently published versions. Alternately, just use one of the two new ones as a testbed, then apply its changes to the old one when I go-live.

However that leaves us with confusingly named projects on the RTD listing/admin side, so possibly best to suck it up & copy over the checkbox state.

Member

bitprophet commented Apr 7, 2014

Realized that the new "docs" site will need to continue showing the current (and soon, "old") versions of the all-in-one site. No real way to avoid this unfortunately - cannot in good conscience remove that info from the Web so we'll just have to deal.

Does mean that I will need to be careful about RTD sites - if I make two new ones as I was planning, I'll have to go through and recheck all the build boxes for all currently published versions. Alternately, just use one of the two new ones as a testbed, then apply its changes to the old one when I go-live.

However that leaves us with confusingly named projects on the RTD listing/admin side, so possibly best to suck it up & copy over the checkbox state.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 7, 2014

Member

Migration checklists!

RTD:

  • Set up two new RTD projects as w/ paramiko; have them build/publish the 'websites' branch for now.
  • Ensure they build OK and link to each other OK (both will require building 2x before this works as both refer to the other's intersphinx.) EDIT: requires changing the code temporarily so intersphinx looks at the rtd subdomains, not the fabfile ones. durrr.
  • Update the intersphinx settings in code back to prod values.
  • Rename fabric project to fabric-docs (so CNAME works)

DNS:

  • CNAME www.fabfile.org to www RTD site
  • CNAME docs.fabfile.org to docs RTD site
  • This is probably the best spot to merge the 'websites' branch into 1.7 and then up thru master. Old project may fail building but hopefully that won't nuke the existing builds.
  • Update the current Fabric project to mirror the fabric-docs project settings
  • Then update the RTD projects' default version entries to be non-'websites'.

Nginx:

  • Change catchall 301 to point to apex domain
  • Change apex/www rule to only handle apex
  • Change apex rule to 301 (not 302!) to www, not docs

Finally:

  • Add Google Analytics to the new project
Member

bitprophet commented Apr 7, 2014

Migration checklists!

RTD:

  • Set up two new RTD projects as w/ paramiko; have them build/publish the 'websites' branch for now.
  • Ensure they build OK and link to each other OK (both will require building 2x before this works as both refer to the other's intersphinx.) EDIT: requires changing the code temporarily so intersphinx looks at the rtd subdomains, not the fabfile ones. durrr.
  • Update the intersphinx settings in code back to prod values.
  • Rename fabric project to fabric-docs (so CNAME works)

DNS:

  • CNAME www.fabfile.org to www RTD site
  • CNAME docs.fabfile.org to docs RTD site
  • This is probably the best spot to merge the 'websites' branch into 1.7 and then up thru master. Old project may fail building but hopefully that won't nuke the existing builds.
  • Update the current Fabric project to mirror the fabric-docs project settings
  • Then update the RTD projects' default version entries to be non-'websites'.

Nginx:

  • Change catchall 301 to point to apex domain
  • Change apex/www rule to only handle apex
  • Change apex rule to 301 (not 302!) to www, not docs

Finally:

  • Add Google Analytics to the new project
@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Just realized that the non-websites-merged branches will not build naturally as I have to use a different settings file path for RTD for this type of setup (sites/<type>/conf.py instead of just letting it find/assume docs/conf.py).

I think I can get away with changing this setting back temporarily (pre launch), building all the old docs (whee), then setting it back. As long as nobody tries to go back and trigger builds of the old versions, should be fine?

Member

bitprophet commented Apr 8, 2014

Just realized that the non-websites-merged branches will not build naturally as I have to use a different settings file path for RTD for this type of setup (sites/<type>/conf.py instead of just letting it find/assume docs/conf.py).

I think I can get away with changing this setting back temporarily (pre launch), building all the old docs (whee), then setting it back. As long as nobody tries to go back and trigger builds of the old versions, should be fine?

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Realized I am a total moron and I can simply take the old/current 'Fabric' project and...rename it. Yes, it means once I change its settings to use the new shit, it will appear semi broken until DNS finishes percolating, but I think that's preferable over forcing RTD to rebuild a bazillion old versions.

I tested that inter-linking works fine with the two new sites now, so tomorrow (tonight??) I can just nuke the fabric-docs one and mutate the existing one instead.

Member

bitprophet commented Apr 8, 2014

Realized I am a total moron and I can simply take the old/current 'Fabric' project and...rename it. Yes, it means once I change its settings to use the new shit, it will appear semi broken until DNS finishes percolating, but I think that's preferable over forcing RTD to rebuild a bazillion old versions.

I tested that inter-linking works fine with the two new sites now, so tomorrow (tonight??) I can just nuke the fabric-docs one and mutate the existing one instead.

@scottjab

This comment has been minimized.

Show comment
Hide comment

scottjab commented Apr 8, 2014

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Minor problem with the 'reuse the old project' idea, RTD doesn't seem to tweak slug/subdomain when a project's name changes. Not too surprising though. Pinged the fine folks there via IRC; will keep the "new old" fabric-docs project around as filler until it is resolved.

The only downside is that older versions of the docs (1.6 and below) will appear to disappear until then. This is OK for a short period of time; if they don't respond by tomorrow midday I'll suck it up and go back to Plan A, "build all the versions! on fabric-docs".

Member

bitprophet commented Apr 8, 2014

Minor problem with the 'reuse the old project' idea, RTD doesn't seem to tweak slug/subdomain when a project's name changes. Not too surprising though. Pinged the fine folks there via IRC; will keep the "new old" fabric-docs project around as filler until it is resolved.

The only downside is that older versions of the docs (1.6 and below) will appear to disappear until then. This is OK for a short period of time; if they don't respond by tomorrow midday I'll suck it up and go back to Plan A, "build all the versions! on fabric-docs".

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Also ran into some odd Travis failures that don't seem like they'd be related to anything o_O The docs part did get overlooked, and I just fixed that, but actual test suite errors were firing off.

May need to compare to e.g. a recent release tag to see WTF, but as of eg f49d6cd the suite was passing...

Member

bitprophet commented Apr 8, 2014

Also ran into some odd Travis failures that don't seem like they'd be related to anything o_O The docs part did get overlooked, and I just fixed that, but actual test suite errors were firing off.

May need to compare to e.g. a recent release tag to see WTF, but as of eg f49d6cd the suite was passing...

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

More docs failures (working on those, derp. circular dependencies FTL!) but also still the regular test failures - ones I cannot recreate locally. Really strange; they don't suggest any obvious 'broken on Travis only' pattern offhand.

EDIT: was testing on 2.5 as that's still my default venv; trying 2.6 now.

Member

bitprophet commented Apr 8, 2014

More docs failures (working on those, derp. circular dependencies FTL!) but also still the regular test failures - ones I cannot recreate locally. Really strange; they don't suggest any obvious 'broken on Travis only' pattern offhand.

EDIT: was testing on 2.5 as that's still my default venv; trying 2.6 now.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Also, the docs subdomain continues to look like the old site even when my local DNS seems updated. Suspect it's because I never did force builds of 1.7/1.8 on the new/temp project; thus they would 404 and maybe that is triggering use of the old content. Building those to see.

Member

bitprophet commented Apr 8, 2014

Also, the docs subdomain continues to look like the old site even when my local DNS seems updated. Suspect it's because I never did force builds of 1.7/1.8 on the new/temp project; thus they would 404 and maybe that is triggering use of the old content. Building those to see.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

And nope, can't recreate the test suite failures on 2.6. Super bizarre. Will need to dig further and possibly stick debug printing in, tomorrow.

Member

bitprophet commented Apr 8, 2014

And nope, can't recreate the test suite failures on 2.6. Super bizarre. Will need to dig further and possibly stick debug printing in, tomorrow.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Also also, the other issue (stale subdomain) isn't resolved after those builds. Clearly trying to tackle all this late in the evening was a stupid idea. Will see what the morning brings.

Member

bitprophet commented Apr 8, 2014

Also also, the other issue (stale subdomain) isn't resolved after those builds. Clearly trying to tackle all this late in the evening was a stupid idea. Will see what the morning brings.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Hm. So at docs.fabfile.org, /en/latest does have the new site, but /en/1.8 does not. So clearly it is hitting the new fabric-docs project (as I updated DNS and saw nothing from RTD yet), but unclear why the builds didn't update w/ new data. Manually forcing new builds of 1.7/1.8 to see if it was just bad timing.

Member

bitprophet commented Apr 8, 2014

Hm. So at docs.fabfile.org, /en/latest does have the new site, but /en/1.8 does not. So clearly it is hitting the new fabric-docs project (as I updated DNS and saw nothing from RTD yet), but unclear why the builds didn't update w/ new data. Manually forcing new builds of 1.7/1.8 to see if it was just bad timing.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

That seems to work, though the redirect at apex of docs.fabfile/fabric-docs.rtd was going to 'latest' not '1.8' despite 1.8 being the default version on the versions page.

However it was not the default on the advanced settings page (was blank) so I set it there and seems to work now. Worried that is somehow distinct from the Versions page dropdown, and may not update when I push a new branch. Will have to see.

Member

bitprophet commented Apr 8, 2014

That seems to work, though the redirect at apex of docs.fabfile/fabric-docs.rtd was going to 'latest' not '1.8' despite 1.8 being the default version on the versions page.

However it was not the default on the advanced settings page (was blank) so I set it there and seems to work now. Worried that is somehow distinct from the Versions page dropdown, and may not update when I push a new branch. Will have to see.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Going to just start building the old docs on fabric-docs so I don't have to worry about the RTD guys having time to migrate the subdomain (or if it's just not really doable.) A few at a time.

Member

bitprophet commented Apr 8, 2014

Going to just start building the old docs on fabric-docs so I don't have to worry about the RTD guys having time to migrate the subdomain (or if it's just not really doable.) A few at a time.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Actually, to limit clutter in the version listings, I'm for now just going to check off the newest version for each of the older release lines that lack the per-branch builds (so ~1.4 backwards). So e.g. 1.3.8 and so on.

It's trivial to rebuild the rest later, and each of those versions includes the previous ones in their changelogs (and versionchanged/added info bits) so this should be fine.

Member

bitprophet commented Apr 8, 2014

Actually, to limit clutter in the version listings, I'm for now just going to check off the newest version for each of the older release lines that lack the per-branch builds (so ~1.4 backwards). So e.g. 1.3.8 and so on.

It's trivial to rebuild the rest later, and each of those versions includes the previous ones in their changelogs (and versionchanged/added info bits) so this should be fine.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 8, 2014

Member

Back to Travis - the "build www without warnings, build docs with warnings, build www with warnings" attempt still fails because the status badge (yes...the travis one...hah) is nonlocal and generates warnings. This wasn't an issue on Paramiko as its website doesn't include the badge.

Not sure if there is a good way to deal with this + the circular dependency junk without just going back to non-warnings-are-errors style builds :(

Member

bitprophet commented Apr 8, 2014

Back to Travis - the "build www without warnings, build docs with warnings, build www with warnings" attempt still fails because the status badge (yes...the travis one...hah) is nonlocal and generates warnings. This wasn't an issue on Paramiko as its website doesn't include the badge.

Not sure if there is a good way to deal with this + the circular dependency junk without just going back to non-warnings-are-errors style builds :(

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 9, 2014

Member

Wonder if moving that sort of nonlocal image into the sidebar would make Sphinx shut up, since it would no longer be part of the ReST and instead be part of the template.

Member

bitprophet commented Apr 9, 2014

Wonder if moving that sort of nonlocal image into the sidebar would make Sphinx shut up, since it would no longer be part of the ReST and instead be part of the template.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 9, 2014

Member

n.b. filed rtfd/readthedocs.org#770 so I can remove the old project w/o it reflecting poorly on anything.

Member

bitprophet commented Apr 9, 2014

n.b. filed rtfd/readthedocs.org#770 so I can remove the old project w/o it reflecting poorly on anything.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 9, 2014

Member

Success, moving the Travis button to be a configurable Alabaster option makes Sphinx STFU.

Member

bitprophet commented Apr 9, 2014

Success, moving the Travis button to be a configurable Alabaster option makes Sphinx STFU.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 10, 2014

Member

Fixed what seems like the only other outstanding doc level warning-fail, meaning those bizarro failing tests are all that is left.

Member

bitprophet commented Apr 10, 2014

Fixed what seems like the only other outstanding doc level warning-fail, meaning those bizarro failing tests are all that is left.

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 10, 2014

Member

Got it, a dumb tweak added to the test runner to skip the new top level Invoke tasks file, was causing the integration test run to invoke both suites; the default suite gets kind of mad if you run it with -H localhost (which was the pattern for all fails - env.host being localhost not None.)

Member

bitprophet commented Apr 10, 2014

Got it, a dumb tweak added to the test runner to skip the new top level Invoke tasks file, was causing the integration test run to invoke both suites; the default suite gets kind of mad if you run it with -H localhost (which was the pattern for all fails - env.host being localhost not None.)

@bitprophet

This comment has been minimized.

Show comment
Hide comment
@bitprophet

bitprophet Apr 10, 2014

Member

I...I think this is done! Only took 3 freakin' years.

Member

bitprophet commented Apr 10, 2014

I...I think this is done! Only took 3 freakin' years.

@bitprophet bitprophet closed this Apr 10, 2014

@tshepang

This comment has been minimized.

Show comment
Hide comment

\0/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment