Epydoc -> Sphinx. #256

Closed
wants to merge 1 commit into
from

Projects

None yet

2 participants

@lndbrg
Contributor
lndbrg commented Jan 23, 2014

First initial conversion. To me it looks good. But Please double check.

I have also deliberately not added the api page to the toc. I leave that up to you.

(The dev requirements are also out of date. invoke 0.6.1 Collection.from_module does not take a name parameter).

@lndbrg
Contributor
lndbrg commented Jan 24, 2014

For #178

@bitprophet
Member

Oooooh. Thanks! Will take a look soon. And yes, I need to update the reqs.txt a bit - I should make sure Travis is building the docs since then it'd catch that sort of thing. I do that for Fabric and it's nice.

EDIT: updated dev-reqs.txt in the website branch. Which is nearly ready to merge.

@bitprophet
Member

Gonna go live w/ WWW first, then tackle this when I have more time. To do then:

  • Check out @lndbrg's branch as a new local branch on my side
  • Generate & add to toctree for 'docs' subsite, poke around to make sure things look good
  • Uncomment the intersphinx stuff in the WWW site and aim it at docs.paramiko.org/en/latest/
  • Remove fabfile.py (which was used only to mirror the Epydoc to my VPS)
  • Merge this branch to 1.10, then up to master
    • Ideally should not need any merge changes since docstrings rarely update right now
  • Modify RTD settings for the 'docs' site to default to 'latest' instead of 'website-178' version
  • Update DNS such that docs.paramiko.org points to the docs site's RTD subdomain as a CNAME
  • Leave the wildcard/landing entries pointing at my VPS
  • Update my VPS' nginx config so that it listens for all subdomains + root entry (i.e. server_name .paramiko.org) and 301's them to www.paramiko.org (which will then be the CNAME resolving to RTD)
    • IOW, remove the existing "serve docs, bounce all others to www" config, should simplify it somewhat.
  • Test that docs subdomain now renders the RTD site and works overall
  • Test that the Intersphinx changes work OK, somehow.
@bitprophet bitprophet added a commit that referenced this pull request Jan 30, 2014
@bitprophet bitprophet Comment out intersphinx pending #256 b8d1724
@bitprophet
Member

Started poking at this now, thanks again!

Trying to break it down into one-page-per-module as that's what I am used to & ought to be easier to navigate. Running into hilarious issues re: autodoc & __module__ at the moment. Autodoc is great but occasionally maddening.

Specifically, some classes are getting imported "early" in the hierarchy and then when they're loaded up "from" their "own" modules (e.g. paramiko.agent.Agent) they appear to have a __module__ of paramiko and not their local module (again e.g. paramiko.agent).

This is borne out by checking this PR's branch by itself, e.g. paramiko.Agent shows up - not paramiko.agent.Agent. Explains why my use of sphinx-apidoc to spit out some boilerplate really wanted to create files specifically for paramiko itself.

So I need to see if the imported-members option helps smooth this over without adding too much other noise, or if there's something else that can be done (without breaking Paramiko's existing __init__.py and its __all__.)

@bitprophet
Member

Yea imported-members doesn't help, probably because these classes have already been "taken" by the higher level module?

Given how many classes internally are implementation details, may be simpler to reverse approach & only document the things explicitly imported into paramiko for now. Gonna keep pokin.

@bitprophet
Member

I was wondering why this was the way it was, doesn't match how __module__ is supposed to work, then I found this horrible thing: https://github.com/paramiko/paramiko/blob/master/paramiko/__init__.py#L92

so-mad.gif

With that gone things work much more like I was expecting \o/ back to the grind...

@bitprophet
Member

Have WIP in the sphinx-256 branch. Renamed all headers, consolidated some files that were logically strongly related, nuked a bunch that had little/no autodoc material and/or were internal implementation details.

Next up is to probably reorganize the TOC into logical subsections (it looks very scattershot as one big list, even with the new headers) and then actually skim the content for tweaks that need making (e.g. a bunch of docstrings have formatting clearly intended to end up as eg literal blocks, which don't quite make it there Sphinx wise.)

@bitprophet
Member

Ran some sed commands to clear up a bunch of the :class: bits (some of them were on method references; and due to an irritating Sphinx quirk, almost all of the actual class ones needed a preceding dot) and now doing a full scan for obviously broken remainders. Then I think it's good enough to publish and move on :)

@bitprophet
Member

Almost done! This has been a massive undertaking even with the initial work from @lndbrg. So many docstrings :)

I'm tempted to make one more pass to remove all the redundant return-type specifiers - many times I see "Returns: a Foo; Return type: Foo" which is just silly/noise.

@bitprophet
Member

OK, that first pass is done! Will quickly scan for redundant return-type info and then that's got to be sufficient for now.

@bitprophet
Member

Good Christ that took a long time. Things are still not 100% perfect, but much much cleaner now, including actual fixes that were needed even if we'd stayed with Epydoc (misleading/outdated info, bad references, bad grammar/punctuation, etc.)

Running one clean build to find any other Sphinx warnings, fixing those, then this is done.

I think I will continue having the build process generate docs, so that the sdist has docs available like it does now, and can then wean people off of that later.

@bitprophet
Member

Dealing with Invoke #116 but if that isn't resolved fast I will just stop including rendered docs for now and take it up w/ anybody who cares enough to notice.

@bitprophet
Member

OK that's all set, now have a release task that builds/moves API docs into docs/, then releases.

Back to the checklist up top!

@bitprophet bitprophet added a commit that referenced this pull request Mar 4, 2014
@bitprophet bitprophet Changelog re #256 83f09e6
@bitprophet
Member

Poked RTD, got worried their endpoint wasn't working with our odd dual site setup, but turns out RTD actually updated just under 2 weeks ago such that it will correctly find all sites targeted at the repository Github is sending the ping from.

Tested it out and we now have automatic builds of all API versions that are checked, as well as the main website (on master). Good times.

@bitprophet
Member

It all works! Holy crap. Closing on account of I merged this and then some.

@bitprophet bitprophet closed this Mar 5, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment