def read_doc(self, docname: str) -> None:
"""Parse a file and add/update inventory entries for the doctree."""
self.env.prepare_settings(docname)
# Add confdir/docutils.conf to dependencies list if exists
docutilsconf = path.join(self.confdir, 'docutils.conf')
if path.isfile(docutilsconf):
self.env.note_dependency(docutilsconf)
with sphinx_domains(self.env), rst.default_role(
docname, self.config.default_role):
doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
# store time of reading, for outdated files detection
# (Some filesystems have coarse timestamp resolution;
# therefore time.time() can be older than filesystem's timestamp.
# For example, FAT32 has 2sec timestamp resolution.)
self.env.all_docs[docname] = max(
time.time(), path.getmtime(self.env.doc2path(docname)))
# cleanup
self.env.temp_data.clear()
self.env.ref_context.clear()
self.write_doctree(docname, doctree)
def read_doc(self, docname):
# type: (unicode) -> None
"""Parse a file and add/update inventory entries for the doctree."""
self.env.prepare_settings(docname)
# Add confdir/docutils.conf to dependencies list if exists
docutilsconf = path.join(self.confdir, 'docutils.conf')
if path.isfile(docutilsconf):
self.env.note_dependency(docutilsconf)
with sphinx_domains(self.env), rst.default_role(docname, self.config.default_role):
doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
# store time of reading, for outdated files detection
# (Some filesystems have coarse timestamp resolution;
# therefore time.time() can be older than filesystem's timestamp.
# For example, FAT32 has 2sec timestamp resolution.)
self.env.all_docs[docname] = max(time.time(),
path.getmtime(self.env.doc2path(docname)))
# cleanup
self.env.temp_data.clear()
self.env.ref_context.clear()
self.write_doctree(docname, doctree)
def get_doctree(path, **kwargs):
"""
Obtain a mostly-rendered Sphinx doctree from the RST file at ``path``.
The returned doctree is parsed to the point where Releases' own objects
(such as Release and Issue nodes) have been injected, but not yet turned
into their final representation (such as HTML tags). This is primarily
useful for the use case of `parse_changelog` in this module; if you want a
real 100%-rendered doctree, try using ``sphinx.io.read_doc`` directly.
Any additional kwargs are passed unmodified into an internal `make_app`
call.
:param str path: A relative or absolute Sphinx sourcedir path.
:returns:
A two-tuple of the generated ``sphinx.application.Sphinx`` app and the
doctree (a ``docutils.document`` object).
.. versionchanged:: 1.6
Added support for passing kwargs to `make_app`.
"""
root, filename = os.path.split(path)
docname, _ = os.path.splitext(filename)
# TODO: this only works for top level changelog files (i.e. ones where
# their dirname is the project/doc root)
app = make_app(srcdir=root, **kwargs)
app.env.temp_data["docname"] = docname
doctree = read_doc(app, app.env, path)
return app, doctree
def read_doc(self, docname, app=None):
# type: (unicode, Sphinx) -> None
"""Parse a file and add/update inventory entries for the doctree."""
self.prepare_settings(docname)
docutilsconf = path.join(self.srcdir, 'docutils.conf')
# read docutils.conf from source dir, not from current dir
OptionParser.standard_config_files[1] = docutilsconf
if path.isfile(docutilsconf):
self.note_dependency(docutilsconf)
with sphinx_domains(self), rst.default_role(docname,
self.config.default_role):
doctree = read_doc(self.app, self, self.doc2path(docname))
# store time of reading, for outdated files detection
# (Some filesystems have coarse timestamp resolution;
# therefore time.time() can be older than filesystem's timestamp.
# For example, FAT32 has 2sec timestamp resolution.)
self.all_docs[docname] = max(time.time(),
path.getmtime(self.doc2path(docname)))
# cleanup
self.temp_data.clear()
self.ref_context.clear()
self.write_doctree(docname, doctree)
def make_html(self, docstring):
with Timer('make_html'):
with open(self.doc_file, 'w') as f:
f.write(docstring)
app = self.app
docname = 'index'
with sphinx_domains(app.builder.env), rst.default_role(
docname, app.builder.env.config.default_role):
doctree = read_doc(app.builder.env.app, app.builder.env,
app.builder.env.doc2path(docname))
for domain in app.builder.env.domains.values():
domain.process_doc(app.builder.env, docname, doctree)
app.emit('doctree-read', doctree)
app.builder.prepare_writing({docname})
doctree = app.builder.env.get_and_resolve_doctree(
docname, app.builder, doctree)
app.builder.write_doc_serialized(docname, doctree)
doctree.settings = app.builder.docsettings
app.builder.secnumbers = app.builder.env.toc_secnumbers.get(
docname, {})
app.builder.fignumbers = app.builder.env.toc_fignumbers.get(
docname, {})
app.builder.imgpath = relative_uri(
app.builder.get_target_uri(docname), '_images')
app.builder.dlpath = relative_uri(
app.builder.get_target_uri(docname), '_downloads')
app.builder.current_docname = docname
app.builder.docwriter.write(doctree, self.destination)
app.builder.docwriter.assemble_parts()
body = app.builder.docwriter.parts['fragment']
return body
def _parse(app: Sphinx, code: str) -> document:
with NamedTemporaryFile("w+", suffix=".rst", dir=app.env.srcdir) as f:
f.write(code)
f.flush()
app.env.prepare_settings(f.name)
with sphinx_domains(app.env), rst.default_role(
f.name, app.config.default_role):
return read_doc(app, app.env, f.name)
def find_autoasdf_directives(env, filename):
docname = env.path2doc(filename)
env.prepare_settings(docname)
with sphinx_domains(env), rst.default_role(docname,
env.config.default_role):
doctree = read_doc(env.app, env, env.doc2path(docname))
return doctree.traverse(schema_def)
def read_doc(self, docname, app=None):
# type: (unicode, Sphinx) -> None
"""Parse a file and add/update inventory entries for the doctree."""
self.prepare_settings(docname)
docutilsconf = path.join(self.srcdir, 'docutils.conf')
# read docutils.conf from source dir, not from current dir
OptionParser.standard_config_files[1] = docutilsconf
if path.isfile(docutilsconf):
self.note_dependency(docutilsconf)
with sphinx_domains(self), rst.default_role(docname, self.config.default_role):
doctree = read_doc(self.app, self, self.doc2path(docname))
# post-processing
for domain in itervalues(self.domains):
domain.process_doc(self, docname, doctree)
# allow extension-specific post-processing
if app:
app.emit('doctree-read', doctree)
# store time of reading, for outdated files detection
# (Some filesystems have coarse timestamp resolution;
# therefore time.time() can be older than filesystem's timestamp.
# For example, FAT32 has 2sec timestamp resolution.)
self.all_docs[docname] = max(
time.time(), path.getmtime(self.doc2path(docname)))
if self.versioning_condition:
# add uids for versioning
versioning.prepare(doctree)
# cleanup
self.temp_data.clear()
self.ref_context.clear()
self.write_doctree(docname, doctree)
start_time = time()
# app.builder.env._read_serial(docnames, app.builder.env.app)
for docname in docnames:
print('docname', docname)
app.emit('env-purge-doc', app.builder.env, docname)
app.builder.env.clear_doc(docname)
# app.builder.env.read_doc(docname, app)
app.builder.env.prepare_settings(docname)
docutilsconf = path.join(app.builder.env.srcdir, 'docutils.conf')
# read docutils.conf from source dir, not from current dir
OptionParser.standard_config_files[1] = docutilsconf
if path.isfile(docutilsconf):
app.builder.env.note_dependency(docutilsconf)
with sphinx_domains(app.builder.env), rst.default_role(docname, app.builder.env.config.default_role):
doctree = read_doc(app.builder.env.app, app.builder.env, app.builder.env.doc2path(docname))
# post-processing
for domain in app.builder.env.domains.values():
domain.process_doc(app.builder.env, docname, doctree)
# allow extension-specific post-processing
if app:
app.emit('doctree-read', doctree)
print('docnames', docnames)
updated_docnames = set(docnames)
print('updated_docnames:', updated_docnames)
# app.builder.write(set(), list(updated_docnames), 'update')
