commit: cc73af5a6990dfa196c889421b8bcb77cf2d25e1 Author: Zac Medico <zmedico <AT> gentoo <DOT> org> AuthorDate: Sun Feb 2 09:35:39 2020 +0000 Commit: Zac Medico <zmedico <AT> gentoo <DOT> org> CommitDate: Mon Feb 3 09:26:35 2020 +0000 URL: https://gitweb.gentoo.org/proj/portage.git/commit/?id=cc73af5a
doc: replace epydoc with sphinx-apidoc + sphinx-epytext Bug: https://bugs.gentoo.org/707820 Signed-off-by: Zac Medico <zmedico <AT> gentoo.org> doc/api/.gitignore | 1 + doc/api/Makefile | 32 ++++++++++++++++++++++++++ doc/api/conf.py | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/api/index.rst | 18 +++++++++++++++ setup.py | 33 ++++++++++++--------------- 5 files changed, 131 insertions(+), 19 deletions(-) diff --git a/doc/api/.gitignore b/doc/api/.gitignore new file mode 100644 index 000000000..796b96d1c --- /dev/null +++ b/doc/api/.gitignore @@ -0,0 +1 @@ +/build diff --git a/doc/api/Makefile b/doc/api/Makefile new file mode 100644 index 000000000..56420a497 --- /dev/null +++ b/doc/api/Makefile @@ -0,0 +1,32 @@ +# Makefile for Sphinx documentation +# + +SPHINX_APIDOC_OPTIONS = members,private-members,undoc-members,show-inheritance,ignore-module-all,inherited-members +export SPHINX_APIDOC_OPTIONS + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = build +TOPDIR = ../.. + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + rm -rf $(BUILDDIR) $(SOURCEDIR)/api + +$(BUILDDIR)/_sources/portage.rst: + mkdir -p "$(BUILDDIR)/_sources" + cp -pPR "$(SOURCEDIR)/conf.py" "$(SOURCEDIR)/index.rst" "$(BUILDDIR)/_sources" + sphinx-apidoc -TPef -o "$(BUILDDIR)/_sources" $(TOPDIR)/lib/_emerge + sphinx-apidoc -TPef -o "$(BUILDDIR)/_sources" $(TOPDIR)/lib/portage $(TOPDIR)/lib/portage/tests + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile $(BUILDDIR)/_sources/portage.rst + @$(SPHINXBUILD) -M $@ "$(BUILDDIR)/_sources" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/api/conf.py b/doc/api/conf.py new file mode 100644 index 000000000..f318ca25d --- /dev/null +++ b/doc/api/conf.py @@ -0,0 +1,66 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +import os +from os import path as osp +import sys + +if osp.isfile(osp.abspath(osp.join(osp.dirname(__file__), "../../../../.portage_not_installed"))): + sys.path.insert(0, osp.abspath(osp.join(osp.dirname(__file__), "../../../../lib"))) +import portage + +# -- Project information ----------------------------------------------------- + +project = 'portage' +copyright = '2020, Gentoo Authors' +author = 'Gentoo Authors' + +# The full version, including alpha/beta/rc tags +release = str(portage.VERSION) + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx_epytext', +] + +# Add any paths that contain templates here, relative to this directory. +# templates_path = [] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +# exclude_patterns = [] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_show_sourcelink = False +html_theme = 'sphinxdoc' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = [] + +autodoc_default_options = dict((opt, True) for opt in + filter(None, os.environ.get('SPHINX_APIDOC_OPTIONS', '').split(','))) diff --git a/doc/api/index.rst b/doc/api/index.rst new file mode 100644 index 000000000..ffaece6c9 --- /dev/null +++ b/doc/api/index.rst @@ -0,0 +1,18 @@ +Portage API Documentation +========================= + +Modules +======= + +.. toctree:: + :maxdepth: 1 + + _emerge + portage + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/setup.py b/setup.py index c62f5f6eb..d337ba49d 100755 --- a/setup.py +++ b/setup.py @@ -30,7 +30,7 @@ import sys # TODO: -# - smarter rebuilds of docs w/ 'install_docbook' and 'install_epydoc'. +# - smarter rebuilds of docs w/ 'install_docbook' and 'install_apidoc'. # Dictionary of scripts. The structure is # key = location in filesystem to install the scripts @@ -135,8 +135,8 @@ class docbook(Command): '-m', 'doc/custom.xsl', f, 'doc/portage.docbook']) -class epydoc(Command): - """ Build API docs using epydoc. """ +class apidoc(Command): + """ Build API docs using apidoc. """ user_options = [ ] @@ -160,14 +160,8 @@ class epydoc(Command): pass process_env['PYTHONPATH'] = pythonpath - subprocess.check_call(['epydoc', '-o', 'epydoc', - '--name', self.distribution.get_name(), - '--url', self.distribution.get_url(), - '-qq', '--no-frames', '--show-imports', - '--exclude', 'portage.tests', - '_emerge', 'portage'], + subprocess.check_call(['make', '-C', 'doc/api', 'html'], env = process_env) - os.remove('epydoc/api-objects.txt') class install_docbook(install_data): @@ -194,8 +188,8 @@ class install_docbook(install_data): install_data.run(self) -class install_epydoc(install_data): - """ install_data for epydoc docs """ +class install_apidoc(install_data): + """ install_data for apidoc docs """ user_options = install_data.user_options + [ ('htmldir=', None, "HTML documentation install directory"), @@ -210,10 +204,11 @@ class install_epydoc(install_data): install_data.finalize_options(self) def run(self): - if not os.path.exists('epydoc/index.html'): - self.run_command('epydoc') + if not os.path.exists('doc/api/build/html/index.html'): + self.run_command('apidoc') self.data_files = [ - (os.path.join(self.htmldir, 'api'), glob.glob('epydoc/*')), + (os.path.join(self.htmldir, 'api'), glob.glob('doc/api/build/html/*.html') + glob.glob('doc/api/build/html/*.js')), + (os.path.join(self.htmldir, 'api/_static'), glob.glob('doc/api/build/html/_static/*')), ] install_data.run(self) @@ -298,8 +293,8 @@ class x_clean(clean): if os.path.isdir('doc/fragment'): remove_tree('doc/fragment') - if os.path.isdir('epydoc'): - remove_tree('epydoc') + if os.path.isdir('doc/api/build'): + remove_tree('doc/api/build') def clean_tests(self): # do not remove incorrect dirs accidentally @@ -699,11 +694,11 @@ setup( 'build_tests': build_tests, 'clean': x_clean, 'docbook': docbook, - 'epydoc': epydoc, + 'apidoc': apidoc, 'install': x_install, 'install_data': x_install_data, 'install_docbook': install_docbook, - 'install_epydoc': install_epydoc, + 'install_apidoc': install_apidoc, 'install_lib': x_install_lib, 'install_scripts': x_install_scripts, 'install_scripts_bin': x_install_scripts_bin,
