[PATCH 0/6] Try harder to get API docs up on readthedocs.org

Anne Mulhern amulhern at redhat.com
Thu Jul 24 14:26:13 UTC 2014


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-doesnt-apply-to.
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 at redhat.com>
> To: anaconda-patches at 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 at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
> 


More information about the anaconda-patches mailing list