I finally have some understanding of sphinx autodoc.
The makefile in doc/ runs sphinx-apidoc before running sphinx-build -- that's where the API docs come from. Since readthedocs runs sphinx-build directly (without running sphinx-apidoc first) there are no API docs generated there. The obvious solution is to keep the API docs in git so they are in place for readthedocs' build. We'll have to update them if we move/add/remove modules, but that should be about it as far as maintenence. We can always run sphinx-apidoc again, change the title in the modules.rst file, add the member-order option throughout, and update them wholesale if we want to.
David Lehman (6): Add API docs. Order module members by position in source instead of alphabetically. Change title of top-level module list to API. Don't remove api docs every time you make a doc target. Mock selinux when building docs. Fix sphinx formatting of clode blocks in devicefactory docstrings.
.gitignore | 4 - blivet/devicefactory.py | 6 +- doc/Makefile | 1 - doc/blivet.devicelibs.rst | 102 +++++++++++++++++++++++ doc/blivet.formats.rst | 120 ++++++++++++++++++++++++++++ doc/blivet.rst | 200 ++++++++++++++++++++++++++++++++++++++++++++++ doc/conf.py | 2 +- doc/index.rst | 2 +- doc/modules.rst | 7 ++ 9 files changed, 434 insertions(+), 10 deletions(-) create mode 100644 doc/blivet.devicelibs.rst create mode 100644 doc/blivet.formats.rst create mode 100644 doc/blivet.rst create mode 100644 doc/modules.rst
These were generated using sphinx-apidoc. --- .gitignore | 4 -- doc/blivet.devicelibs.rst | 91 +++++++++++++++++++++++ doc/blivet.formats.rst | 107 +++++++++++++++++++++++++++ doc/blivet.rst | 179 ++++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 2 +- doc/modules.rst | 7 ++ 6 files changed, 385 insertions(+), 5 deletions(-) create mode 100644 doc/blivet.devicelibs.rst create mode 100644 doc/blivet.formats.rst create mode 100644 doc/blivet.rst create mode 100644 doc/modules.rst
diff --git a/.gitignore b/.gitignore index 54c7439..3f37b3b 100644 --- a/.gitignore +++ b/.gitignore @@ -2,10 +2,6 @@ .*.swp blivet*.tar.gz blivet*.tar.bz2 -doc/blivet.devicelibs.rst -doc/blivet.formats.rst -doc/blivet.rst -doc/modules.rst doc/_build po/*.gmo po/*.po diff --git a/doc/blivet.devicelibs.rst b/doc/blivet.devicelibs.rst new file mode 100644 index 0000000..44ca8b5 --- /dev/null +++ b/doc/blivet.devicelibs.rst @@ -0,0 +1,91 @@ +devicelibs Package +================== + +:mod:`btrfs` Module +------------------- + +.. automodule:: blivet.devicelibs.btrfs + :members: + :undoc-members: + :show-inheritance: + +:mod:`crypto` Module +-------------------- + +.. automodule:: blivet.devicelibs.crypto + :members: + :undoc-members: + :show-inheritance: + +:mod:`dasd` Module +------------------ + +.. automodule:: blivet.devicelibs.dasd + :members: + :undoc-members: + :show-inheritance: + +:mod:`dm` Module +---------------- + +.. automodule:: blivet.devicelibs.dm + :members: + :undoc-members: + :show-inheritance: + +:mod:`edd` Module +----------------- + +.. automodule:: blivet.devicelibs.edd + :members: + :undoc-members: + :show-inheritance: + +:mod:`loop` Module +------------------ + +.. automodule:: blivet.devicelibs.loop + :members: + :undoc-members: + :show-inheritance: + +:mod:`lvm` Module +----------------- + +.. automodule:: blivet.devicelibs.lvm + :members: + :undoc-members: + :show-inheritance: + +:mod:`mdraid` Module +-------------------- + +.. automodule:: blivet.devicelibs.mdraid + :members: + :undoc-members: + :show-inheritance: + +:mod:`mpath` Module +------------------- + +.. automodule:: blivet.devicelibs.mpath + :members: + :undoc-members: + :show-inheritance: + +:mod:`raid` Module +------------------ + +.. automodule:: blivet.devicelibs.raid + :members: + :undoc-members: + :show-inheritance: + +:mod:`swap` Module +------------------ + +.. automodule:: blivet.devicelibs.swap + :members: + :undoc-members: + :show-inheritance: + diff --git a/doc/blivet.formats.rst b/doc/blivet.formats.rst new file mode 100644 index 0000000..7a00a25 --- /dev/null +++ b/doc/blivet.formats.rst @@ -0,0 +1,107 @@ +formats Package +=============== + +:mod:`formats` Package +---------------------- + +.. automodule:: blivet.formats + :members: + :undoc-members: + :show-inheritance: + +:mod:`biosboot` Module +---------------------- + +.. automodule:: blivet.formats.biosboot + :members: + :undoc-members: + :show-inheritance: + +:mod:`disklabel` Module +----------------------- + +.. automodule:: blivet.formats.disklabel + :members: + :undoc-members: + :show-inheritance: + +:mod:`dmraid` Module +-------------------- + +.. automodule:: blivet.formats.dmraid + :members: + :undoc-members: + :show-inheritance: + +:mod:`fs` Module +---------------- + +.. automodule:: blivet.formats.fs + :members: + :undoc-members: + :show-inheritance: + +:mod:`fslabel` Module +--------------------- + +.. automodule:: blivet.formats.fslabel + :members: + :undoc-members: + :show-inheritance: + +:mod:`fslabeling` Module +------------------------ + +.. automodule:: blivet.formats.fslabeling + :members: + :undoc-members: + :show-inheritance: + +:mod:`luks` Module +------------------ + +.. automodule:: blivet.formats.luks + :members: + :undoc-members: + :show-inheritance: + +:mod:`lvmpv` Module +------------------- + +.. automodule:: blivet.formats.lvmpv + :members: + :undoc-members: + :show-inheritance: + +:mod:`mdraid` Module +-------------------- + +.. automodule:: blivet.formats.mdraid + :members: + :undoc-members: + :show-inheritance: + +:mod:`multipath` Module +----------------------- + +.. automodule:: blivet.formats.multipath + :members: + :undoc-members: + :show-inheritance: + +:mod:`prepboot` Module +---------------------- + +.. automodule:: blivet.formats.prepboot + :members: + :undoc-members: + :show-inheritance: + +:mod:`swap` Module +------------------ + +.. automodule:: blivet.formats.swap + :members: + :undoc-members: + :show-inheritance: + diff --git a/doc/blivet.rst b/doc/blivet.rst new file mode 100644 index 0000000..ed79389 --- /dev/null +++ b/doc/blivet.rst @@ -0,0 +1,179 @@ +blivet Package +============== + +:mod:`blivet` Package +--------------------- + +.. automodule:: blivet.__init__ + :members: + :undoc-members: + :show-inheritance: + +:mod:`arch` Module +------------------ + +.. automodule:: blivet.arch + :members: + :undoc-members: + :show-inheritance: + +:mod:`deviceaction` Module +-------------------------- + +.. automodule:: blivet.deviceaction + :members: + :undoc-members: + :show-inheritance: + +:mod:`devicefactory` Module +--------------------------- + +.. automodule:: blivet.devicefactory + :members: + :undoc-members: + :show-inheritance: + +:mod:`devices` Module +--------------------- + +.. automodule:: blivet.devices + :members: + :undoc-members: + :show-inheritance: + +:mod:`devicetree` Module +------------------------ + +.. automodule:: blivet.devicetree + :members: + :undoc-members: + :show-inheritance: + +:mod:`errors` Module +-------------------- + +.. automodule:: blivet.errors + :members: + :undoc-members: + :show-inheritance: + +:mod:`fcoe` Module +------------------ + +.. automodule:: blivet.fcoe + :members: + :undoc-members: + :show-inheritance: + +:mod:`flags` Module +------------------- + +.. automodule:: blivet.flags + :members: + :undoc-members: + :show-inheritance: + +:mod:`i18n` Module +------------------ + +.. automodule:: blivet.i18n + :members: + :undoc-members: + :show-inheritance: + +:mod:`iscsi` Module +------------------- + +.. automodule:: blivet.iscsi + :members: + :undoc-members: + :show-inheritance: + +:mod:`partitioning` Module +-------------------------- + +.. automodule:: blivet.partitioning + :members: + :undoc-members: + :show-inheritance: + +:mod:`partspec` Module +---------------------- + +.. automodule:: blivet.partspec + :members: + :undoc-members: + :show-inheritance: + +:mod:`platform` Module +---------------------- + +.. automodule:: blivet.platform + :members: + :undoc-members: + :show-inheritance: + +:mod:`pyudev` Module +-------------------- + +.. automodule:: blivet.pyudev + :members: + :undoc-members: + :show-inheritance: + +:mod:`size` Module +------------------ + +.. automodule:: blivet.size + :members: + :undoc-members: + :show-inheritance: + +:mod:`storage_log` Module +------------------------- + +.. automodule:: blivet.storage_log + :members: + :undoc-members: + :show-inheritance: + +:mod:`tsort` Module +------------------- + +.. automodule:: blivet.tsort + :members: + :undoc-members: + :show-inheritance: + +:mod:`udev` Module +------------------ + +.. automodule:: blivet.udev + :members: + :undoc-members: + :show-inheritance: + +:mod:`util` Module +------------------ + +.. automodule:: blivet.util + :members: + :undoc-members: + :show-inheritance: + +:mod:`zfcp` Module +------------------ + +.. automodule:: blivet.zfcp + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + + blivet.devicelibs + blivet.formats + diff --git a/doc/index.rst b/doc/index.rst index 8c534ee..5c32438 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,7 +9,7 @@ Welcome to Blivet's documentation! Contents:
.. toctree:: - :maxdepth: 3 + :maxdepth: 4
intro modules diff --git a/doc/modules.rst b/doc/modules.rst new file mode 100644 index 0000000..ca9d073 --- /dev/null +++ b/doc/modules.rst @@ -0,0 +1,7 @@ +API +=== + +.. toctree:: + :maxdepth: 4 + + blivet
sphinx-apidocs does not provide any way to specify global options (eg: autodoc_member_order), nor is it currently possible to specify automodule options that take values via SPHINX_APIDOC_OPTIONS. --- doc/blivet.devicelibs.rst | 11 +++++++++++ doc/blivet.formats.rst | 13 +++++++++++++ doc/blivet.rst | 21 +++++++++++++++++++++ doc/modules.rst | 4 ++-- 4 files changed, 47 insertions(+), 2 deletions(-)
diff --git a/doc/blivet.devicelibs.rst b/doc/blivet.devicelibs.rst index 44ca8b5..1fcce0c 100644 --- a/doc/blivet.devicelibs.rst +++ b/doc/blivet.devicelibs.rst @@ -8,6 +8,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`crypto` Module -------------------- @@ -16,6 +17,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`dasd` Module ------------------ @@ -24,6 +26,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`dm` Module ---------------- @@ -32,6 +35,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`edd` Module ----------------- @@ -40,6 +44,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`loop` Module ------------------ @@ -48,6 +53,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`lvm` Module ----------------- @@ -56,6 +62,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`mdraid` Module -------------------- @@ -64,6 +71,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`mpath` Module ------------------- @@ -72,6 +80,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`raid` Module ------------------ @@ -80,6 +89,7 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`swap` Module ------------------ @@ -88,4 +98,5 @@ devicelibs Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
diff --git a/doc/blivet.formats.rst b/doc/blivet.formats.rst index 7a00a25..6a900f4 100644 --- a/doc/blivet.formats.rst +++ b/doc/blivet.formats.rst @@ -8,6 +8,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`biosboot` Module ---------------------- @@ -16,6 +17,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`disklabel` Module ----------------------- @@ -24,6 +26,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`dmraid` Module -------------------- @@ -32,6 +35,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`fs` Module ---------------- @@ -40,6 +44,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`fslabel` Module --------------------- @@ -48,6 +53,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`fslabeling` Module ------------------------ @@ -56,6 +62,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`luks` Module ------------------ @@ -64,6 +71,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`lvmpv` Module ------------------- @@ -72,6 +80,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`mdraid` Module -------------------- @@ -80,6 +89,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`multipath` Module ----------------------- @@ -88,6 +98,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`prepboot` Module ---------------------- @@ -96,6 +107,7 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`swap` Module ------------------ @@ -104,4 +116,5 @@ formats Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
diff --git a/doc/blivet.rst b/doc/blivet.rst index ed79389..92ca5a6 100644 --- a/doc/blivet.rst +++ b/doc/blivet.rst @@ -8,6 +8,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`arch` Module ------------------ @@ -16,6 +17,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`deviceaction` Module -------------------------- @@ -24,6 +26,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`devicefactory` Module --------------------------- @@ -32,6 +35,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`devices` Module --------------------- @@ -40,6 +44,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`devicetree` Module ------------------------ @@ -48,6 +53,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`errors` Module -------------------- @@ -56,6 +62,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`fcoe` Module ------------------ @@ -64,6 +71,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`flags` Module ------------------- @@ -72,6 +80,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`i18n` Module ------------------ @@ -80,6 +89,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`iscsi` Module ------------------- @@ -88,6 +98,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`partitioning` Module -------------------------- @@ -96,6 +107,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`partspec` Module ---------------------- @@ -104,6 +116,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`platform` Module ---------------------- @@ -112,6 +125,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`pyudev` Module -------------------- @@ -120,6 +134,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`size` Module ------------------ @@ -128,6 +143,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`storage_log` Module ------------------------- @@ -136,6 +152,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`tsort` Module ------------------- @@ -144,6 +161,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`udev` Module ------------------ @@ -152,6 +170,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`util` Module ------------------ @@ -160,6 +179,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
:mod:`zfcp` Module ------------------ @@ -168,6 +188,7 @@ blivet Package :members: :undoc-members: :show-inheritance: + :member-order: bysource
Subpackages ----------- diff --git a/doc/modules.rst b/doc/modules.rst index ca9d073..07803ac 100644 --- a/doc/modules.rst +++ b/doc/modules.rst @@ -1,5 +1,5 @@ -API -=== +blivet +======
.. toctree:: :maxdepth: 4
--- doc/modules.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/modules.rst b/doc/modules.rst index 07803ac..ca9d073 100644 --- a/doc/modules.rst +++ b/doc/modules.rst @@ -1,5 +1,5 @@ -blivet -====== +API +===
.. toctree:: :maxdepth: 4
--- doc/Makefile | 1 - 1 file changed, 1 deletion(-)
diff --git a/doc/Makefile b/doc/Makefile index 2fc38ee..d3aad66 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -45,7 +45,6 @@ clean: -rm -rf $(BUILDDIR)/*
apidoc: - -rm $(addprefix ./, $(MODULE_NAMES)) $(SPHINXAPIDOC) -o . $(SOURCEDIR)
html: apidoc
----- Original Message -----
From: "David Lehman" dlehman@redhat.com To: anaconda-patches@lists.fedorahosted.org Sent: Wednesday, July 23, 2014 3:24:01 PM Subject: [PATCH 4/6] Don't remove api docs every time you make a doc target.
doc/Makefile | 1 - 1 file changed, 1 deletion(-)
diff --git a/doc/Makefile b/doc/Makefile index 2fc38ee..d3aad66 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -45,7 +45,6 @@ clean: -rm -rf $(BUILDDIR)/*
apidoc:
- -rm $(addprefix ./, $(MODULE_NAMES)) $(SPHINXAPIDOC) -o . $(SOURCEDIR)
html: apidoc
1.9.3
anaconda-patches mailing list anaconda-patches@lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
Need to get rid of variable MODULE_NAMES as well.
- mulhern
--- doc/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/doc/conf.py b/doc/conf.py index 3b54936..cedaeea 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -293,6 +293,9 @@ intersphinx_mapping = {'https://docs.python.org/2': None} # This was taken directly from here: # http://read-the-docs.readthedocs.org/en/latest/faq.html#i-get-import-errors-... # I only added the __getitem__ method. +# NOTE: this can be removed whenever we move to sphinx-1.3, at which point we'll +# be able to use autodoc_mock_imports (value is a list of modules to be +# mocked). class Mock(object):
__all__ = [] @@ -318,6 +321,6 @@ class Mock(object): def __getitem__(cls, key): return cls.__getattr__(key)
-MOCK_MODULES = ['parted', 'block', 'pycryptsetup', 'pykickstart', 'pykickstart.constants', '_ped'] +MOCK_MODULES = ['parted', 'block', 'pycryptsetup', 'pykickstart', 'pykickstart.constants', '_ped', 'selinux'] for mod_name in MOCK_MODULES: sys.modules[mod_name] = Mock()
--- blivet/devicefactory.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/blivet/devicefactory.py b/blivet/devicefactory.py index bb8edef..7926d39 100644 --- a/blivet/devicefactory.py +++ b/blivet/devicefactory.py @@ -113,7 +113,7 @@ class DeviceFactory(object): device stacks like lvm with md pvs.
Simplified call trace for creation of a new LV in a new VG with - partition PVs: + partition PVs::
LVMFactory.configure PartitionSetFactory.configure # set up PVs on partitions @@ -122,7 +122,7 @@ class DeviceFactory(object):
Simplified call trace for creation of a new LV in a new VG with a single - MD PV with member partitions on multiple disks: + MD PV with member partitions on multiple disks::
LVMOnMDFactory.configure MDFactory.configure @@ -141,7 +141,7 @@ class DeviceFactory(object): "data" in the Blivet instance's device tree, that volume group will be used instead of creating a new one. If the already-defined "data" volume group exists on disk its size will not be changed, but if it has not - been written to disk it will be adjusted to hold the new logical volume. + been written to disk it will be adjusted to hold the new logical volume::
import blivet
Here's a link to a screenshot:
http://dlehman.fedorapeople.org/blivet-docs-screenshot-20140723.0.png
(What?! You couldn't envision it after simply reading the patches?)
On Wed, 2014-07-23 at 14:44 -0500, David Lehman wrote:
Here's a link to a screenshot:
http://dlehman.fedorapeople.org/blivet-docs-screenshot-20140723.0.png
Looks really good. ACK.
On Wed, Jul 23, 2014 at 02:23:57PM -0500, David Lehman wrote:
I finally have some understanding of sphinx autodoc.
The makefile in doc/ runs sphinx-apidoc before running sphinx-build -- that's where the API docs come from. Since readthedocs runs sphinx-build directly (without running sphinx-apidoc first) there are no API docs generated there. The obvious solution is to keep the API docs in git so they are in place for readthedocs' build. We'll have to update them if we move/add/remove modules, but that should be about it as far as maintenence. We can always run sphinx-apidoc again, change the title in the modules.rst file, add the member-order option throughout, and update them wholesale if we want to.
Great! These look good to me.
On Wed, 2014-07-23 at 14:23 -0500, David Lehman wrote:
I finally have some understanding of sphinx autodoc.
The makefile in doc/ runs sphinx-apidoc before running sphinx-build -- that's where the API docs come from. Since readthedocs runs sphinx-build directly (without running sphinx-apidoc first) there are no API docs generated there. The obvious solution is to keep the API docs in git so they are in place for readthedocs' build. We'll have to update them if we move/add/remove modules, but that should be about it as far as maintenence. We can always run sphinx-apidoc again, change the title in the modules.rst file, add the member-order option throughout, and update them wholesale if we want to.
David Lehman (6): Add API docs. Order module members by position in source instead of alphabetically. Change title of top-level module list to API. Don't remove api docs every time you make a doc target. Mock selinux when building docs. Fix sphinx formatting of clode blocks in devicefactory docstrings.
^^^^^ typo ?
.gitignore | 4 - blivet/devicefactory.py | 6 +- doc/Makefile | 1 - doc/blivet.devicelibs.rst | 102 +++++++++++++++++++++++ doc/blivet.formats.rst | 120 ++++++++++++++++++++++++++++ doc/blivet.rst | 200 ++++++++++++++++++++++++++++++++++++++++++++++ doc/conf.py | 2 +- doc/index.rst | 2 +- doc/modules.rst | 7 ++ 9 files changed, 434 insertions(+), 10 deletions(-) create mode 100644 doc/blivet.devicelibs.rst create mode 100644 doc/blivet.formats.rst create mode 100644 doc/blivet.rst create mode 100644 doc/modules.rst
It seems like some of the most significant changes were motivated by issues with readthedocs.
Another option to re-adding all these autogenerated rst files is to enable virtualenv in readthedocs and write a small setup.py file. It would run only in the readthedocs context, quitting if the READTHEDOCS environment variable was not set, but otherwise generating those .rst files. Changes to the .rst files are readily sedable, awkable, Pythonable and so could be done in the setup.py file. I know this seems like overkill, but maintaining by hand a bunch of boring, repetitive .rst files that can be auto-generated is kind of depressing.
A slightly less ambitious option is to do all these task in conf.py instead of having setup.py and using virtualenv. We already have the MOCK_MODULES hack in conf.py, so the ice has definitely been broken.
I filed a bug about being unable to set member-order default anywhere, but I also found out that member-order is a bit brittle: https://bitbucket.org/birkenfeld/sphinx/issue/628/autoclass-member-order-doe.... It would be nice if sphinx was a bit more like javadoc, with an alphabetized index somewhere and methods in the order that they were declared in the file, but I don't think it has reached that state yet.
- mulhern
----- Original Message -----
From: "David Lehman" dlehman@redhat.com To: anaconda-patches@lists.fedorahosted.org Sent: Wednesday, July 23, 2014 3:23:57 PM Subject: [PATCH 0/6] Try harder to get API docs up on readthedocs.org
I finally have some understanding of sphinx autodoc.
The makefile in doc/ runs sphinx-apidoc before running sphinx-build -- that's where the API docs come from. Since readthedocs runs sphinx-build directly (without running sphinx-apidoc first) there are no API docs generated there. The obvious solution is to keep the API docs in git so they are in place for readthedocs' build. We'll have to update them if we move/add/remove modules, but that should be about it as far as maintenence. We can always run sphinx-apidoc again, change the title in the modules.rst file, add the member-order option throughout, and update them wholesale if we want to.
David Lehman (6): Add API docs. Order module members by position in source instead of alphabetically. Change title of top-level module list to API. Don't remove api docs every time you make a doc target. Mock selinux when building docs. Fix sphinx formatting of clode blocks in devicefactory docstrings.
.gitignore | 4 - blivet/devicefactory.py | 6 +- doc/Makefile | 1 - doc/blivet.devicelibs.rst | 102 +++++++++++++++++++++++ doc/blivet.formats.rst | 120 ++++++++++++++++++++++++++++ doc/blivet.rst | 200 ++++++++++++++++++++++++++++++++++++++++++++++ doc/conf.py | 2 +- doc/index.rst | 2 +- doc/modules.rst | 7 ++ 9 files changed, 434 insertions(+), 10 deletions(-) create mode 100644 doc/blivet.devicelibs.rst create mode 100644 doc/blivet.formats.rst create mode 100644 doc/blivet.rst create mode 100644 doc/modules.rst
-- 1.9.3
anaconda-patches mailing list anaconda-patches@lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
On 07/24/2014 09:26 AM, Anne Mulhern wrote:
It seems like some of the most significant changes were motivated by issues with readthedocs.
Another option to re-adding all these autogenerated rst files is to enable virtualenv in readthedocs and write a small setup.py file. It would run only in the readthedocs context, quitting if the READTHEDOCS environment variable was not set, but otherwise generating those .rst files. Changes to the .rst files are readily sedable, awkable, Pythonable and so could be done in the setup.py file. I know this seems like overkill, but maintaining by hand a bunch of boring, repetitive .rst files that can be auto-generated is kind of depressing.
It hadn't occurred to me to put a filthy hack into the setup.py file. After spending too much time reading the readthedocs code to figure out how it finds the docs I have a patch to setup.py that will probably do the trick. I'm leaning slightly toward the setup.py hack since at least it will be mostly out of sight/mind.
A slightly less ambitious option is to do all these task in conf.py instead of having setup.py and using virtualenv. We already have the MOCK_MODULES hack in conf.py, so the ice has definitely been broken.
The mocking is like a small drill-hole IMO compared to the sledgehammer of running external programs from conf.py.
I filed a bug about being unable to set member-order default anywhere, but I also found out that member-order is a bit brittle: https://bitbucket.org/birkenfeld/sphinx/issue/628/autoclass-member-order-doe.... It would be nice if sphinx was a bit more like javadoc, with an alphabetized index somewhere and methods in the order that they were declared in the file, but I don't think it has reached that state yet.
It does include an alphabetized index by default. The member-order limitation is sad, but we don't currently use inherited-members.
- mulhern
----- Original Message -----
From: "David Lehman" dlehman@redhat.com To: anaconda-patches@lists.fedorahosted.org Sent: Wednesday, July 23, 2014 3:23:57 PM Subject: [PATCH 0/6] Try harder to get API docs up on readthedocs.org
I finally have some understanding of sphinx autodoc.
The makefile in doc/ runs sphinx-apidoc before running sphinx-build -- that's where the API docs come from. Since readthedocs runs sphinx-build directly (without running sphinx-apidoc first) there are no API docs generated there. The obvious solution is to keep the API docs in git so they are in place for readthedocs' build. We'll have to update them if we move/add/remove modules, but that should be about it as far as maintenence. We can always run sphinx-apidoc again, change the title in the modules.rst file, add the member-order option throughout, and update them wholesale if we want to.
David Lehman (6): Add API docs. Order module members by position in source instead of alphabetically. Change title of top-level module list to API. Don't remove api docs every time you make a doc target. Mock selinux when building docs. Fix sphinx formatting of clode blocks in devicefactory docstrings.
.gitignore | 4 - blivet/devicefactory.py | 6 +- doc/Makefile | 1 - doc/blivet.devicelibs.rst | 102 +++++++++++++++++++++++ doc/blivet.formats.rst | 120 ++++++++++++++++++++++++++++ doc/blivet.rst | 200 ++++++++++++++++++++++++++++++++++++++++++++++ doc/conf.py | 2 +- doc/index.rst | 2 +- doc/modules.rst | 7 ++ 9 files changed, 434 insertions(+), 10 deletions(-) create mode 100644 doc/blivet.devicelibs.rst create mode 100644 doc/blivet.formats.rst create mode 100644 doc/blivet.rst create mode 100644 doc/modules.rst
-- 1.9.3
anaconda-patches mailing list anaconda-patches@lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
anaconda-patches mailing list anaconda-patches@lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
anaconda-patches@lists.fedorahosted.org
-
Anne Mulhern -
Brian C. Lane -
David Lehman -
Martin Kolman -
Vratislav Podzimek