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).
Epydoc -> Sphinx.
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.
Gonna go live w/ WWW first, then tackle this when I have more time. To do then:
Comment out intersphinx pending #256
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__.)
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.
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
With that gone things work much more like I was expecting \o/ back to the grind...
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.)
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 :)
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.
OK, that first pass is done! Will quickly scan for redundant return-type info and then that's got to be sufficient for now.
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.
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.
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!
Changelog re #256
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.
It all works! Holy crap. Closing on account of I merged this and then some.