1 |
commit: cc73af5a6990dfa196c889421b8bcb77cf2d25e1 |
2 |
Author: Zac Medico <zmedico <AT> gentoo <DOT> org> |
3 |
AuthorDate: Sun Feb 2 09:35:39 2020 +0000 |
4 |
Commit: Zac Medico <zmedico <AT> gentoo <DOT> org> |
5 |
CommitDate: Mon Feb 3 09:26:35 2020 +0000 |
6 |
URL: https://gitweb.gentoo.org/proj/portage.git/commit/?id=cc73af5a |
7 |
|
8 |
doc: replace epydoc with sphinx-apidoc + sphinx-epytext |
9 |
|
10 |
Bug: https://bugs.gentoo.org/707820 |
11 |
Signed-off-by: Zac Medico <zmedico <AT> gentoo.org> |
12 |
|
13 |
doc/api/.gitignore | 1 + |
14 |
doc/api/Makefile | 32 ++++++++++++++++++++++++++ |
15 |
doc/api/conf.py | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
16 |
doc/api/index.rst | 18 +++++++++++++++ |
17 |
setup.py | 33 ++++++++++++--------------- |
18 |
5 files changed, 131 insertions(+), 19 deletions(-) |
19 |
|
20 |
diff --git a/doc/api/.gitignore b/doc/api/.gitignore |
21 |
new file mode 100644 |
22 |
index 000000000..796b96d1c |
23 |
--- /dev/null |
24 |
+++ b/doc/api/.gitignore |
25 |
@@ -0,0 +1 @@ |
26 |
+/build |
27 |
|
28 |
diff --git a/doc/api/Makefile b/doc/api/Makefile |
29 |
new file mode 100644 |
30 |
index 000000000..56420a497 |
31 |
--- /dev/null |
32 |
+++ b/doc/api/Makefile |
33 |
@@ -0,0 +1,32 @@ |
34 |
+# Makefile for Sphinx documentation |
35 |
+# |
36 |
+ |
37 |
+SPHINX_APIDOC_OPTIONS = members,private-members,undoc-members,show-inheritance,ignore-module-all,inherited-members |
38 |
+export SPHINX_APIDOC_OPTIONS |
39 |
+ |
40 |
+# You can set these variables from the command line. |
41 |
+SPHINXOPTS = |
42 |
+SPHINXBUILD = sphinx-build |
43 |
+SOURCEDIR = . |
44 |
+BUILDDIR = build |
45 |
+TOPDIR = ../.. |
46 |
+ |
47 |
+# Put it first so that "make" without argument is like "make help". |
48 |
+help: |
49 |
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
50 |
+ |
51 |
+clean: |
52 |
+ rm -rf $(BUILDDIR) $(SOURCEDIR)/api |
53 |
+ |
54 |
+$(BUILDDIR)/_sources/portage.rst: |
55 |
+ mkdir -p "$(BUILDDIR)/_sources" |
56 |
+ cp -pPR "$(SOURCEDIR)/conf.py" "$(SOURCEDIR)/index.rst" "$(BUILDDIR)/_sources" |
57 |
+ sphinx-apidoc -TPef -o "$(BUILDDIR)/_sources" $(TOPDIR)/lib/_emerge |
58 |
+ sphinx-apidoc -TPef -o "$(BUILDDIR)/_sources" $(TOPDIR)/lib/portage $(TOPDIR)/lib/portage/tests |
59 |
+ |
60 |
+.PHONY: help Makefile |
61 |
+ |
62 |
+# Catch-all target: route all unknown targets to Sphinx using the new |
63 |
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). |
64 |
+%: Makefile $(BUILDDIR)/_sources/portage.rst |
65 |
+ @$(SPHINXBUILD) -M $@ "$(BUILDDIR)/_sources" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
66 |
|
67 |
diff --git a/doc/api/conf.py b/doc/api/conf.py |
68 |
new file mode 100644 |
69 |
index 000000000..f318ca25d |
70 |
--- /dev/null |
71 |
+++ b/doc/api/conf.py |
72 |
@@ -0,0 +1,66 @@ |
73 |
+# Configuration file for the Sphinx documentation builder. |
74 |
+# |
75 |
+# This file only contains a selection of the most common options. For a full |
76 |
+# list see the documentation: |
77 |
+# http://www.sphinx-doc.org/en/master/config |
78 |
+ |
79 |
+# -- Path setup -------------------------------------------------------------- |
80 |
+ |
81 |
+# If extensions (or modules to document with autodoc) are in another directory, |
82 |
+# add these directories to sys.path here. If the directory is relative to the |
83 |
+# documentation root, use os.path.abspath to make it absolute, like shown here. |
84 |
+# |
85 |
+# import os |
86 |
+# import sys |
87 |
+# sys.path.insert(0, os.path.abspath('.')) |
88 |
+ |
89 |
+import os |
90 |
+from os import path as osp |
91 |
+import sys |
92 |
+ |
93 |
+if osp.isfile(osp.abspath(osp.join(osp.dirname(__file__), "../../../../.portage_not_installed"))): |
94 |
+ sys.path.insert(0, osp.abspath(osp.join(osp.dirname(__file__), "../../../../lib"))) |
95 |
+import portage |
96 |
+ |
97 |
+# -- Project information ----------------------------------------------------- |
98 |
+ |
99 |
+project = 'portage' |
100 |
+copyright = '2020, Gentoo Authors' |
101 |
+author = 'Gentoo Authors' |
102 |
+ |
103 |
+# The full version, including alpha/beta/rc tags |
104 |
+release = str(portage.VERSION) |
105 |
+ |
106 |
+# -- General configuration --------------------------------------------------- |
107 |
+ |
108 |
+# Add any Sphinx extension module names here, as strings. They can be |
109 |
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom |
110 |
+# ones. |
111 |
+extensions = [ |
112 |
+ 'sphinx.ext.autodoc', |
113 |
+ 'sphinx_epytext', |
114 |
+] |
115 |
+ |
116 |
+# Add any paths that contain templates here, relative to this directory. |
117 |
+# templates_path = [] |
118 |
+ |
119 |
+# List of patterns, relative to source directory, that match files and |
120 |
+# directories to ignore when looking for source files. |
121 |
+# This pattern also affects html_static_path and html_extra_path. |
122 |
+# exclude_patterns = [] |
123 |
+ |
124 |
+# -- Options for HTML output ------------------------------------------------- |
125 |
+ |
126 |
+# The theme to use for HTML and HTML Help pages. See the documentation for |
127 |
+# a list of builtin themes. |
128 |
+# |
129 |
+html_show_sourcelink = False |
130 |
+html_theme = 'sphinxdoc' |
131 |
+ |
132 |
+# Add any paths that contain custom static files (such as style sheets) here, |
133 |
+# relative to this directory. They are copied after the builtin static files, |
134 |
+# so a file named "default.css" will overwrite the builtin "default.css". |
135 |
+# html_static_path = [] |
136 |
+ |
137 |
+autodoc_default_options = dict((opt, True) for opt in |
138 |
+ filter(None, os.environ.get('SPHINX_APIDOC_OPTIONS', '').split(','))) |
139 |
|
140 |
diff --git a/doc/api/index.rst b/doc/api/index.rst |
141 |
new file mode 100644 |
142 |
index 000000000..ffaece6c9 |
143 |
--- /dev/null |
144 |
+++ b/doc/api/index.rst |
145 |
@@ -0,0 +1,18 @@ |
146 |
+Portage API Documentation |
147 |
+========================= |
148 |
+ |
149 |
+Modules |
150 |
+======= |
151 |
+ |
152 |
+.. toctree:: |
153 |
+ :maxdepth: 1 |
154 |
+ |
155 |
+ _emerge |
156 |
+ portage |
157 |
+ |
158 |
+Indices and tables |
159 |
+================== |
160 |
+ |
161 |
+* :ref:`genindex` |
162 |
+* :ref:`modindex` |
163 |
+* :ref:`search` |
164 |
|
165 |
diff --git a/setup.py b/setup.py |
166 |
index c62f5f6eb..d337ba49d 100755 |
167 |
--- a/setup.py |
168 |
+++ b/setup.py |
169 |
@@ -30,7 +30,7 @@ import sys |
170 |
|
171 |
|
172 |
# TODO: |
173 |
-# - smarter rebuilds of docs w/ 'install_docbook' and 'install_epydoc'. |
174 |
+# - smarter rebuilds of docs w/ 'install_docbook' and 'install_apidoc'. |
175 |
|
176 |
# Dictionary of scripts. The structure is |
177 |
# key = location in filesystem to install the scripts |
178 |
@@ -135,8 +135,8 @@ class docbook(Command): |
179 |
'-m', 'doc/custom.xsl', f, 'doc/portage.docbook']) |
180 |
|
181 |
|
182 |
-class epydoc(Command): |
183 |
- """ Build API docs using epydoc. """ |
184 |
+class apidoc(Command): |
185 |
+ """ Build API docs using apidoc. """ |
186 |
|
187 |
user_options = [ |
188 |
] |
189 |
@@ -160,14 +160,8 @@ class epydoc(Command): |
190 |
pass |
191 |
process_env['PYTHONPATH'] = pythonpath |
192 |
|
193 |
- subprocess.check_call(['epydoc', '-o', 'epydoc', |
194 |
- '--name', self.distribution.get_name(), |
195 |
- '--url', self.distribution.get_url(), |
196 |
- '-qq', '--no-frames', '--show-imports', |
197 |
- '--exclude', 'portage.tests', |
198 |
- '_emerge', 'portage'], |
199 |
+ subprocess.check_call(['make', '-C', 'doc/api', 'html'], |
200 |
env = process_env) |
201 |
- os.remove('epydoc/api-objects.txt') |
202 |
|
203 |
|
204 |
class install_docbook(install_data): |
205 |
@@ -194,8 +188,8 @@ class install_docbook(install_data): |
206 |
install_data.run(self) |
207 |
|
208 |
|
209 |
-class install_epydoc(install_data): |
210 |
- """ install_data for epydoc docs """ |
211 |
+class install_apidoc(install_data): |
212 |
+ """ install_data for apidoc docs """ |
213 |
|
214 |
user_options = install_data.user_options + [ |
215 |
('htmldir=', None, "HTML documentation install directory"), |
216 |
@@ -210,10 +204,11 @@ class install_epydoc(install_data): |
217 |
install_data.finalize_options(self) |
218 |
|
219 |
def run(self): |
220 |
- if not os.path.exists('epydoc/index.html'): |
221 |
- self.run_command('epydoc') |
222 |
+ if not os.path.exists('doc/api/build/html/index.html'): |
223 |
+ self.run_command('apidoc') |
224 |
self.data_files = [ |
225 |
- (os.path.join(self.htmldir, 'api'), glob.glob('epydoc/*')), |
226 |
+ (os.path.join(self.htmldir, 'api'), glob.glob('doc/api/build/html/*.html') + glob.glob('doc/api/build/html/*.js')), |
227 |
+ (os.path.join(self.htmldir, 'api/_static'), glob.glob('doc/api/build/html/_static/*')), |
228 |
] |
229 |
install_data.run(self) |
230 |
|
231 |
@@ -298,8 +293,8 @@ class x_clean(clean): |
232 |
if os.path.isdir('doc/fragment'): |
233 |
remove_tree('doc/fragment') |
234 |
|
235 |
- if os.path.isdir('epydoc'): |
236 |
- remove_tree('epydoc') |
237 |
+ if os.path.isdir('doc/api/build'): |
238 |
+ remove_tree('doc/api/build') |
239 |
|
240 |
def clean_tests(self): |
241 |
# do not remove incorrect dirs accidentally |
242 |
@@ -699,11 +694,11 @@ setup( |
243 |
'build_tests': build_tests, |
244 |
'clean': x_clean, |
245 |
'docbook': docbook, |
246 |
- 'epydoc': epydoc, |
247 |
+ 'apidoc': apidoc, |
248 |
'install': x_install, |
249 |
'install_data': x_install_data, |
250 |
'install_docbook': install_docbook, |
251 |
- 'install_epydoc': install_epydoc, |
252 |
+ 'install_apidoc': install_apidoc, |
253 |
'install_lib': x_install_lib, |
254 |
'install_scripts': x_install_scripts, |
255 |
'install_scripts_bin': x_install_scripts_bin, |