2 # -*- coding: utf-8 -*-
6 from pathlib import Path
7 sys.path.append(str(Path(__file__).parent))
9 extensions = [ 'sphinx.ext.autodoc', 'elisp' ]
11 # The suffix of source filenames.
12 source_suffix = '.rst'
14 # The master toctree document.
17 # General information about the project.
19 copyright = u'2009-2022, Carl Worth and many others'
21 location = os.path.dirname(__file__)
23 for pathdir in ['.', '..']:
24 version_file = os.path.join(location,pathdir,'version.txt')
25 if os.path.exists(version_file):
26 with open(version_file,'r') as infile:
27 version=infile.read().replace('\n','')
30 sys.path.insert(0, os.path.join(location, '..', 'bindings', 'python-cffi', 'build', 'stage'))
32 # read generated config
33 for pathdir in ['.', '..']:
34 conf_file = os.path.join(location,pathdir,'sphinx.config')
35 if os.path.exists(conf_file):
36 with open(conf_file,'r') as infile:
37 exec(''.join(infile.readlines()))
39 # The full version, including alpha/beta/rc tags.
42 # List of patterns, relative to source directory, that match files and
43 # directories to ignore when looking for source files.
44 exclude_patterns = ['_build']
46 if tags.has('WITH_EMACS'):
47 # Hacky reimplementation of include to workaround limitations of
49 lines = ['.. include:: /../emacs/rstdoc.rsti\n\n'] # in the source tree
50 for file in ('notmuch.rsti', 'notmuch-lib.rsti', 'notmuch-hello.rsti', 'notmuch-show.rsti', 'notmuch-tag.rsti', 'notmuch-tree.rsti'):
51 lines.extend(open(rsti_dir+'/'+file))
52 rst_epilog = ''.join(lines)
55 # If we don't have emacs (or the user configured --without-emacs),
56 # don't build the notmuch-emacs docs, as they need emacs to generate
57 # the docstring include files
58 exclude_patterns.append('notmuch-emacs.rst')
60 if not tags.has('WITH_PYTHON'):
61 exclude_patterns.append('python-bindings.rst')
63 # The name of the Pygments (syntax highlighting) style to use.
64 pygments_style = 'sphinx'
66 # -- Options for HTML output ----------------------------------------------
68 # The theme to use for HTML and HTML Help pages. See the documentation for
69 # a list of builtin themes.
70 html_theme = 'default'
72 # prevent generation of python module index
73 html_domain_indices=[]
75 # Add any paths that contain custom static files (such as style sheets) here,
76 # relative to this directory. They are copied after the builtin static files,
77 # so a file named "default.css" will overwrite the builtin "default.css".
80 # Output file base name for HTML help builder.
81 htmlhelp_basename = 'notmuchdoc'
83 # Disable SmartyPants, as it mangles command lines.
84 # Despite the name, this actually affects manual pages as well.
85 html_use_smartypants = False
88 # - https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url
89 # - https://manpages.debian.org/
90 manpages_url = 'https://manpages.debian.org/{page}.{section}.html'
92 # -- Options for manual page output ---------------------------------------
94 # One entry per manual page. List of tuples
95 # (source start file, name, description, authors, manual section).
97 notmuch_authors = u'Carl Worth and many others'
99 man_make_section_directory = False
102 ('man1/notmuch', 'notmuch',
103 u'thread-based email index, search, and tagging',
104 [notmuch_authors], 1),
106 ('man1/notmuch-address', 'notmuch-address',
107 u'output addresses from matching messages',
108 [notmuch_authors], 1),
110 ('man1/notmuch-compact', 'notmuch-compact',
111 u'compact the notmuch database',
112 [notmuch_authors], 1),
114 ('man1/notmuch-config', 'notmuch-config',
115 u'access notmuch configuration file',
116 [notmuch_authors], 1),
118 ('man1/notmuch-count', 'notmuch-count',
119 u'count messages matching the given search terms',
120 [notmuch_authors], 1),
122 ('man1/notmuch-dump', 'notmuch-dump',
123 u'creates a plain-text dump of the tags of each message',
124 [notmuch_authors], 1),
126 ('man1/notmuch-emacs-mua', 'notmuch-emacs-mua',
127 u'send mail with notmuch and emacs',
128 [notmuch_authors], 1),
130 ('man1/notmuch-git', 'notmuch-git',
131 u'manage notmuch tags with git',
132 [notmuch_authors], 1),
134 ('man1/notmuch-git', 'nmbug',
135 u'manage notmuch bugs with git',
136 [notmuch_authors], 1),
138 ('man5/notmuch-hooks', 'notmuch-hooks',
139 u'hooks for notmuch',
140 [notmuch_authors], 5),
142 ('man1/notmuch-insert', 'notmuch-insert',
143 u'add a message to the maildir and notmuch database',
144 [notmuch_authors], 1),
146 ('man1/notmuch-new', 'notmuch-new',
147 u'incorporate new mail into the notmuch database',
148 [notmuch_authors], 1),
150 ('man7/notmuch-properties', 'notmuch-properties',
151 u'notmuch message property conventions and documentation',
152 [notmuch_authors], 7),
154 ('man1/notmuch-reindex', 'notmuch-reindex',
155 u're-index matching messages',
156 [notmuch_authors], 1),
158 ('man1/notmuch-reply', 'notmuch-reply',
159 u'constructs a reply template for a set of messages',
160 [notmuch_authors], 1),
162 ('man1/notmuch-restore', 'notmuch-restore',
163 u'restores the tags from the given file (see notmuch dump)',
164 [notmuch_authors], 1),
166 ('man1/notmuch-search', 'notmuch-search',
167 u'search for messages matching the given search terms',
168 [notmuch_authors], 1),
170 ('man7/notmuch-search-terms', 'notmuch-search-terms',
171 u'syntax for notmuch queries',
172 [notmuch_authors], 7),
174 ('man1/notmuch', 'notmuch-setup',
175 u'getting started with notmuch',
176 [notmuch_authors], 1),
178 ('man7/notmuch-sexp-queries', 'notmuch-sexp-queries',
179 u's-expression syntax for notmuch queries',
180 [notmuch_authors], 7),
182 ('man1/notmuch-show', 'notmuch-show',
183 u'show messages matching the given search terms',
184 [notmuch_authors], 1),
186 ('man1/notmuch-tag', 'notmuch-tag',
187 u'add/remove tags for all messages matching the search terms',
188 [notmuch_authors], 1),
191 # If true, show URL addresses after external links.
192 #man_show_urls = False
194 # -- Options for Texinfo output -------------------------------------------
196 # Grouping the document tree into Texinfo files. List of tuples
197 # (source start file, target name, title, author,
198 # dir menu entry, description, category)
199 # If true, do not generate a @detailmenu in the "Top" node's menu.
200 texinfo_no_detailmenu = True
202 texinfo_documents = [
203 ('notmuch-emacs', 'notmuch-emacs', u'notmuch-emacs documentation',
204 notmuch_authors, 'notmuch-emacs',
205 'emacs based front-end for notmuch', 'Miscellaneous'),
208 # generate texinfo list from man page list
209 texinfo_documents += [
211 x[0], # source start file
213 x[1] + u' documentation', # title
215 x[1], # dir menu entry
217 'Miscellaneous' # category
218 ) for x in man_pages]
221 import docutils.nodes
222 # define nmconfig role and directive for config items.
223 app.add_object_type('nmconfig','nmconfig',
224 indextemplate='pair: configuration item; %s',
225 ref_nodeclass=docutils.nodes.generated,
226 objname='config item' )