Framework for building docs

[jaraco]

I'd be happy to just continue to use ReadTheDocs for documentation hosting, but I've been frustrated with the amount of boilerplate they require just to configure a basic build.

I recently stumbled onto this doc which describes a way for publishing docs as GitHub pages using Sphinx. I think that approach may be lighter weight than RTD (though it does add another dependency on GitHub).

• [ ] Determine hosting strategy.

Other concerns to address in this issue:

• [ ] Auto-build API docs (including overview in init.doc).
• [ ] Support (and prefer) markdown in docstrings (this answer suggests that sphinx-autodoc2 may be helpful here.

[jaraco]

I've been working from an assumption that docs should be in a ./docs folder, but lately I've been thinking that contradicts some of the coherent philosophies. In particular, if it's a sphinx config, it will need lots of boilerplate to generate the conf.py file and the index with table of contents and links to modules.

For many of the projects I maintain, there are no project-specific changes to the docs folder other than listing the modules to be documented. Moreover, it seems that the module docstring of the __init__.py module might be a good place for an overview. If the docs builder could use autodiscovery to find the modules and build the API docs, and if the code base was amenable to rich narrative and guidance, it might be unnecessary to have a separate bit of narrative for many (most?) projects. And maybe even the README should be in the __init__ module's docstring.

Other projects, like setuptools have extensive documentation outside the code. For these projects, I'm wondering if the docs should be in the code base at all. Here are some reasons why maybe the code should be in the same repo and branch as the code:

• synchronization: sometimes a project will want to atomically commit a change to the code and docs at the same time, or direct a user to make a corresponding change to the docs along with a behavior change (or vice versa).
• consolidation: having a single repo makes it easier to pass around the docs and code together. API docs (docstrings) and narrative docs outside the code are committed in the same place.
• discovery: it's easier to discover and browse docs when they're in the same main branch of the code repo.
• distribution: some projects may wish to distribute their docs with the source distribution to aid downstream packagers with building and publishing docs for a given artifact.
• attribution: By tagging and releasing docs with the code, the docs can be referenced by version and reference a particular version of the behavior.

Some of these advantages can potentially be met by using submodules, having the docs in a separate git repo or branch, but linking them into the repo so a version of the docs is linked to a version of the code.

Advantages to keeping the docs separate include:

• independence: narrative docs can provide version-agnostic guidance and evolve independently.
• simplicity: docs can live in the root of the branch/repo without concern about other structures; code can build and run without coordinating with docs.
• integratability: the docs can be integrated into a publishing system and that system doesn't have to be aware of code concerns.
• separation of concerns: a docs repo or branch could attract a different audience and apply different policies.
• distinguished approaches: docs may require different workflows, timelines, and management.
• optionality: narrative docs may be unnecessary for many projects.
• composability: with narrative docs in a separate tree, they're more easily composed with docs from other projects.

I find these tradeoffs to be compelling in both directions. I'm finding the separate docs slightly more compelling because the (automatic) path from separate docs to inline docs is more obvious than the inverse.

My plan is this:

• First and foremost, support rich API docs in the code.
• Allow for links to docs hosted elsewhere (separate repo/hosting)
• Possibly support narrative docs in the repo.