1+ """This module provides functions to create documentation for plugins or
2+ custom modules/packages automatically."""
3+
4+ # TODO: Add custom module/package support
5+
6+ # =============================================================================
7+ # >> IMPORTS
8+ # =============================================================================
9+ # Python
10+ import sys
11+
12+ # Source.Python
13+ from paths import PLUGIN_PATH
14+
15+
16+ # =============================================================================
17+ # >> FUNCTIONS
18+ # =============================================================================
19+ def project_exists (name ):
20+ """Return True if a Sphinx project for a plugin exists.
21+
22+ :param str name: The name of the plugin to test.
23+ """
24+ return (PLUGIN_PATH / name / 'doc' ).isdir ()
25+
26+ def create_project (name , author , project_name = None , version = '1' ):
27+ """Start a new Sphinx project for a plugin or custom module/package.
28+
29+ :param str name: The name of the plugin or custom module/package.
30+ :param str author: The name of the author.
31+ :param str project_name: The project name that will be displayed in the
32+ documentation. If None ``name`` will be used.
33+ :param str version: The project version.
34+ """
35+ from sphinx .quickstart import main
36+
37+ args = [
38+ '' , # Will be skipped.
39+ '-q' , # Don't start the interactive mode
40+ ]
41+
42+ if project_name is None :
43+ project_name = name
44+
45+ args .append ('-p {0}' .format (project_name ))
46+ args .append ('-a {0}' .format (author ))
47+ args .append ('-v {0}' .format (version ))
48+
49+ # TODO:
50+ # Also test if the plugin is loaded to avoid site effects, because load()
51+ # wasn't called
52+ plugin_dir = PLUGIN_PATH / name
53+ if not plugin_dir .isdir ():
54+ raise NameError ('"{0}" is not a valid plugin.' .format (name ))
55+
56+ project_dir = plugin_dir / 'doc'
57+ if not project_dir .isdir ():
58+ project_dir .mkdir ()
59+
60+ args .extend ([
61+ str (project_dir ),
62+ '--sep' , # Separate rst and build directory
63+ '--ext-autodoc' , # Enable autodoc
64+ '--no-makefile' ,
65+ '--no-batchfile'
66+ ])
67+
68+ # Hacky, but required, because sphinx is reading sys.argv even if you pass
69+ # a list to main()
70+ old_argv = sys .argv
71+ sys .argv = args
72+ try :
73+ main (sys .argv )
74+ except :
75+ raise
76+ finally :
77+ sys .argv = old_argv
78+ sys .argv = old_argv
79+
80+ def generate_rst_files (name ):
81+ """Generate *.rst files for a plugin or custom module/package.
82+
83+ :param str name: The name of the plugin or custom module/package.
84+ """
85+ plugin_dir = PLUGIN_PATH / name
86+ project_dir = plugin_dir / 'doc' / 'source'
87+ if not project_dir .isdir ():
88+ raise NameError (
89+ 'Create a project before trying to generate *.rst files.' )
90+
91+ from sphinx .apidoc import main
92+ args = [
93+ '' , # Will be skipped.
94+ '-e' , # Separate pages/files for every module
95+ '-o' ,
96+ str (project_dir ),
97+ str (plugin_dir ), # Package to document
98+ str (project_dir ), # Exclude the doc directory
99+ ]
100+
101+ # Hacky, but required, because sphinx is reading sys.argv even if you pass
102+ # a list to main()
103+ old_argv = sys .argv
104+ sys .argv = args
105+ try :
106+ main (sys .argv )
107+ except :
108+ raise
109+ finally :
110+ sys .argv = old_argv
111+
112+ def build_documentation (name ):
113+ """Build the documentation for a plugin or custom module/package.
114+
115+ :param str name: The name of the plugin or custom module/package.
116+ """
117+ plugin_dir = PLUGIN_PATH / name
118+ project_dir = plugin_dir / 'doc'
119+ if not project_dir .isdir ():
120+ raise NameError (
121+ 'Create a project before trying to build a documentation.' )
122+
123+ source_dir = project_dir / 'source'
124+ build_dir = project_dir / 'build'
125+
126+ from sphinx import main
127+ args = [
128+ '' , # Will be skipped.
129+ str (source_dir ),
130+ str (build_dir ),
131+ ]
132+
133+ # Hacky, but required, because sphinx is reading sys.argv even if you pass
134+ # a list to main()
135+ old_argv = sys .argv
136+ sys .argv = args
137+ try :
138+ main (sys .argv )
139+ except SystemExit as e :
140+ if e .code != 0 :
141+ raise
142+ finally :
143+ sys .argv = old_argv
0 commit comments