Initial logic for Sphinx build of API docs - replacing epydoc #3641
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mwichmann
force-pushed
the
wip-sphinx-apidocs
branch
2 times, most recently
from
cfd6519 to
9e61bf3
Compare
First cut includes a Makefile as generated by Sphinx plumbling, needs to be wired into sconscripts instead. A few regular scons files are updated to address build errors/warnings. Signed-off-by: Mats Wichmann <mats@linux.com>
Signed-off-by: Mats Wichmann <mats@linux.com>
autoclasstoc enabled, but not particularly used yet. Signed-off-by: Mats Wichmann <mats@linux.com>
Signed-off-by: Mats Wichmann <mats@linux.com>
Signed-off-by: Mats Wichmann <mats@linux.com>
Opinion time - when special members are included in the docs, the output isn't really readable, it's too cluttered. Don't seem to be able to get the autoclasstoc stuff working, which was supposed to help with that. Signed-off-by: Mats Wichmann <mats@linux.com>
Split this patchset so it contains only the Sphinx-build configuration itself, and not any docstring changes suggested by running Sphinx. Signed-off-by: Mats Wichmann <mats@linux.com>
mwichmann
force-pushed
the
wip-sphinx-apidocs
branch
from
6c92a77 to
261f1d1
Compare
|
Re: docstring style. Didn't we discuss using Googles style? |
|
RE: "++" modules, can we get Sphinx to ignore them? |
in a way... by not looking deeper in Tools, they do get ignored, but I can't call them out by name to be ignored for the same reason they cause trouble if processed. |
Yes, and that's what I've been using recently. |
|
I think if you add a blurb to the wiki page and assuming I can just do |
bdbaddog
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
General setup for Sphinx build - config, style, etc.
A few regular scons files are updated to address build errors/warnings.
TODO:
build/doc/APISpecific errors:
aixc++, c++, g++, hpc++, sgic++, sunc++index.rst:9: WARNING: toctree contains reference to nonexisting document 'SCons.Tool.packaging.'WARNING: autodoc: failed to determine Null(0x7F706BF19210) to be documented.the following exception was raised: cannot unpack non-iterable Null object(SCons' Null is a hack - no checkers like it either)Fixes #3604 #3121
Signed-off-by: Mats Wichmann mats@linux.com
Contributor Checklist:
src/CHANGES.txt(and read theREADME.txtin that directory)