Package: rst2json
GitHub|PyPI|Issues|ChangelogContentsInstallationCommand-Line UsageLibrary UsageConvenience FunctionDocutils WritersConfiguration OptionsNew Optionssplit_section_levelIgnored OptionsJSON Output Structurerst2jsonrenders areStructuredTextdocument as HTML or (Xe)LaTeX, but —
unlikeDocutils’ builtin converters, which produce a complete output document
— it outputs a JSON object in which the document “frontmatter” (title,
subtitle, bibliographic fields, etc.) has been broken out from the body and
split into multiple fields.  By combining this output with a templating system
likeJinja, the user can perform more powerful & more customizable templating
than is possible with Docutils’ built-in template support.  Version 0.3.0 even
introduces the ability to split apart documents at section boundaries, thereby
making it possible to convert a single input document into multiple output
files.Sample templates that make use of the library’s output, along with a sample
application for splitting sections into separate files, can be found inthe repository’sexamples/directory.Installationrst2jsonrequires Python 3.7 or higher.  Just usepipfor Python 3 (You have pip, right?) to installrst2jsonand its dependencies:python3 -m pip install rst2jsonCommand-Line Usagerst2jsonprovides a single command, also namedrst2json, that converts
an input reStructuredText document to markup organized into a JSON object:rst2json [--format <FMT>] [<docutils options>] [<infile> [<outfile>]]The target markup format is specified with the-for--formatoption.
Valid values (case insensitive) are:html(default)Alias forhtml4.  When Docutils eventually changesrst2html.pyto
produce HTML 5 output instead of HTML 4, this alias will likewise update to
point tohtml5.html4HTML 4 / XHTML 1.0 output, based on the Docutils writer used forrst2html4.py.  A CSS stylesheet (such as thehtml4css1.cssstylesheet distributed with Docutils) must be added to the final document in
order for everything to render properly.html5HTML 5 output, based on the Docutils writer used forrst2html4.py.  A
CSS stylesheet (such as theminimal.cssandplain.cssstylesheets
distributed with Docutils) must be added to the final document in order for
everything to render properly.latexLaTeX output, based on the Docutils writer used forrst2latex.pylatex2eAlias forlatexxetexAlias forxelatexxelatexXeLaTeX output, based on the Docutils writer used forrst2xetex.pyIn addition to the--formatoption, therst2jsoncommand accepts all
options that Docutils’rst2html4.py,rst2html5.py,rst2latex.py,
andrst2xetex.pycommands accept, and it can also be configured via aDocutils configuration filethe same way as the
respective Docutils commands.  Additionalrst2json-specific options are
also accepted; see “Configuration Options” for details.Library UsageConvenience FunctionNew in version 0.2.0rst2json.core.rst2json(source,format='html',options=None,config_files=None,destination_path=None)rst2jsonprovides arst2json.core.rst2json()function for rendering &
splitting reStructuredText into adictdirectly within Python.sourcespecifies the input reStructuredText markup.  It can be a path to a
file (a string), a file-like object (withread()andclose()methods),
or a path-like object.formatis a string specifying the markup format to produce.  It has the
same set of possible values as the--formatoption to therst2jsoncommand.  Alternatively, it may be set directly to an instance of a Docutils
writer class.optionssets values for Docutils settings.  When non-None, it must be adictthat maps option names to option values.  Option names must be given
as listed at <https://docutils.sourceforge.io/docs/user/config.html>, i.e., no
leading hyphens, with internal hyphens replaced with underscores.  Option
values must be of the appropriate Python type, e.g.,boolfor on/off
switches orList[str]for comma-separated values.  Both standard Docutils
options and therst2json-specific options listed under “Configuration
Options” are accepted.config_filesis a list of file paths specifying the Docutils configuration
files to read from; ifNone, configuration is read from the files specified
in theDOCUTILSCONFIGenvironment variable, or from the standard
configuration files if that is not set.  Settings in configuration files
override any conflicting settings given inoptions.  Note that, whenconfig_filesis non-None, Docutils configuration filesnotin the
list will not be read.Starting in version 0.4.0, if you want to append to the list of config files
instead of replacing it, you can call therst2json.core.get_docutils_config_files()function to get a list of config
file paths Docutils will read from based on the current environment; simply
append your config files to this list and pass the result torst2json(),
and all of the files (should they exist) will be read.destination_pathis a path to a file (which need not exist) which
stylesheet paths in HTML<link>tags will be rewritten relative to; ifNone, the paths are rewritten relative to the current directory.  This
parameter is only relevant when emitting HTML withmath_outputset tohtmlwith a stylesheet argument.Docutils WritersThe actual rendering & conversion to JSON is done by custom Writer classes
inheriting from Docutils’ built-in Writers.  Users familiar with Docutils can
use these Writers directly in combination with other Docutils machinery.Therst2json.writers.get_json_writer_class()function can be used to
retrieve a specific Writer class by case-insensitive name.  The classes and
their names are as follows:NamesClasshtml,html4rst2json.writers.html4.Writerhtml5rst2json.writers.html5.Writerlatex,latex2erst2json.writers.latex.Writerxelatex,xetexrst2json.writers.xelatex.WriterEach Writer’stranslate()method setswriter.json_datato the final
JSON structure as adictand setswriter.outputtojson_dataas a
JSON-serialized string.  Afterassemble_parts()is then called,writer.parts["json_data"]will also equal the JSONdict.Configuration OptionsNew OptionsIn addition to the standard Docutils options,rst2jsonaccepts the
following options, both via configuration files and (for the command) via the
command line.  When setting these options via a configuration file, they should
be placed in an[rst2json]section.split_section_levelNew in version 0.3.0Set this option to an integer value.  Setting it to a positive number causes
the content body to be split up into an"intro"field (all content before
the start of the first section) and a"sections"field (each section
represented as an object).  The sections’ subsections are split up as well, up
to a depth given by the value ofsplit_section_level.  Setting this option
to zero disables section splitting; setting it to a negative number causes all
sections at all depths to be split up.As an example, consider the following document:Text before sections, except after C.Section 1=========.._foo:Lorem ipsum yadda yadda yadda.Section 2========='Twas brillig, and the slithy toves did gyre and gimble in the wabe.Section 2.1-----------.._bar:All mimsy were the borogoves, and the mome raths outgrabe.Section 2.1.1~~~~~~~~~~~~~Beware the Jabberwock, my son!Processing this document withsplit_section_levelset to 1 will produce a
JSON document in which thecontentobject’sbodyfield is replaced with
the following fields (Some fields have been omitted for brevity):{"intro":"<p>Text before sections, except after C.</p>","sections":[{"title":"Section 1","ids":["section-1"],"depth":1,"body":"<p id=\"foo\">Lorem ipsum yadda yadda yadda.</p>\n"},{"title":"Section 2","ids":["section-2"],"depth":1,"body":"<p>'Twas brillig, and the slithy toves did gyre and gimble in the wabe.</p>\n<div class=\"section\" id=\"section-2-1\">\n<h2>Section 2.1</h2>\n<p id=\"bar\">All mimsy were the borogoves, and the mome raths outgrabe.</p>\n<div class=\"section\" id=\"section-2-1-1\">\n<h3>Section 2.1.1</h3>\n<p>Beware the Jabberwock, my son!</p>\n</div>\n</div>"}]}Processing with the option set to 2 causes all top-level sections’ bodies to be
split up into"intro"and"sections"like so:{"intro":"<p>Text before sections, except after C.</p>","sections":[{"title":"Section 1","ids":["section-1"],"depth":1,"intro":"<p id=\"foo\">Lorem ipsum yadda yadda yadda.</p>","sections":[]},{"title":"Section 2","ids":["section-2"],"depth":1,"intro":"<p>'Twas brillig, and the slithy toves did gyre and gimble in the wabe.</p>","sections":[{"title":"Section 2.1","ids":["section-2-1"],"depth":2,"body":"<p id=\"bar\">All mimsy were the borogoves, and the mome raths outgrabe.</p>\n<div class=\"section\" id=\"section-2-1-1\">\n<h3>Section 2.1.1</h3>\n<p>Beware the Jabberwock, my son!</p>\n</div>"}]}]}Setting the option to 3 will in turn cause the “Section 2.1” object to also be
split up, and so forth.Default: 0.  Command line option:--split-section-levelIgnored Optionsrst2jsonignores the following Docutils configuration options, as they have
no effect on its operation:documentoptionslatex_preamblestylesheet_pathstylesheettemplateuse_latex_abstractuse_latex_docinfoIn addition, theembed_stylesheetandstylesheet_dirsoptions only have
an effect when emitting HTML withmath_outputset tohtmlwith a
stylesheet argument.JSON Output StructureThe below description divides strings into the following types:Arendered stringis a string containing markup in the target format (HTML
or LaTeX).  Rendered strings are stripped of leading & trailing newlines.Astripped stringis a string in which characters with special meaning to
the format are escaped but all other markup has been removed; in addition,
in stripped strings with corresponding rendered strings, newlines and tabs
are replaced with space characters.For example, under HTML, ifcontent.titleis"<i>War &amp;Peace</i>", thencontent.title_strippedwould be"War &amp; Peace".Unqualified (neither rendered nor stripped) strings are expected to never
contain any special characters.The output fromrst2jsonis a JSON object containing the following fields:contentobjectThe input document converted to the target format and broken up into the
following fields:titlerendered string ornullThe document title, derived from a lone top-level section title ifdoctitle_xformis enabled, ornullif no title was specified ordoctitle_xformwas not enabled.subtitlerendered string ornullThe document subtitle, derived from a lone second-level section title
after the document title ifdoctitle_xformis enabled, ornullif
no subtitle was specified ordoctitle_xformwas not enabled.title_strippedstripped string ornullThetitlefield, but with non-escaping markup removed.  This field
can be used to populate an HTML document’s<title>tag.subtitle_strippedstripped string ornullThesubtitlefield, but with non-escaping markup removed.  This field
can be used to populate an HTML document’s<title>tag.document_idslist of stringsA list of all IDs assigned to the parseddocumentnode.  Such IDs
should be attached to the topmost or near-topmost structure of the final
templated document using HTML’sidattribute or (Xe)LaTeX’s\labelcommand.document_classeslist of stringsA list of classes attached to the parseddocumentnode.subtitle_idslist of stringsA list of all IDs assigned to the document subtitle, or the empty list if
the document does not have a subtitle.  Such IDs should be attached to
the templated subtitle using HTML’sidattribute or (Xe)LaTeX’s\labelcommand.subtitle_classeslist of stringsA list of classes attached to the document subtitle, or the empty list if
the document does not have a subtitle.authorslist of rendered stringsA list of all authors specified in the:Author:and/or:Authors:bibliographic fields, in the order that they appear in the input.headerrendered string ornullThe rendered contents of theheader::directive from the document, ornullif there was no such directive.  Markup for using it as a header
is not included.footerrendered string ornullThe rendered contents of thefooter::directive from the document, ornullif there was no such directive.  Markup for using it as a footer
is not included.docinfolist of objectsThe document’sbibliographic fields(excluding the dedication &
abstract) in the order that they appear in the input, each one
represented as an object with the following fields:typestringFor registered fields, this is the name of the Docutils node class
that represents the field — i.e., the English name of the field in
lowercase (e.g.,"author").  For unregistered fields, this is the
string"field".namerendered stringFor registered fields, this is the name of the field in the document’s
language (e.g.,"Author").  For unregistered fields, this is the
name of the field as it appears in the input.valueWhentypeis"authors"(plural), this is a list of author
names as rendered strings.  For all other values oftype, this is
a rendered string.Note that, whentypeis"address", whitespace invalueis
significant, andvalueshould be wrapped in<pre>tags or
similar.value_strippedThevaluefield, but with non-escaping markup removed.  Whentypeis"authors"(plural), this is a list of stripped
strings.  For all other values oftype, this is a stripped string.
This field can be used to populate thecontentattribute of a<meta>tag.classeslist of stringsA list of classes attached to the field.  Normally, for registered
fields, this list is empty, while for unregistered fields it contains
a single element equal to the field name converted to a valid class
token.  This field can be used to set the CSS class of the HTML
structure that contains the rendered field.abstractrendered string ornullThe rendered contents of the document’s:Abstract:field, ornullif there was no such field.  The abstract title and enclosing block are
not included.dedicationrendered string ornullThe rendered contents of the document’s:Dedication:field, ornullif there was no such field.  The dedication title and enclosing
block are not included.bodyrendered stringThe rendered contents of the rest of the document after the frontmatter.
This field is only present ifsplit_section_level(See
“Configuration Options”) is 0.introrendered stringThe rendered content after the frontmatter, but before the first section.
This field is only present ifsplit_section_levelis not 0.sectionslist of objectsA list of the top-level sections of the document, each one represented as
an object with the below fields.  This field is only present ifsplit_section_levelis not 0.titlerendered stringThe section titlesubtitlerendered string ornullThe section subtitle, derived from a lone second-level title after the
section title ifsectsubtitle_xformis enabled, ornullif no
subtitle was specified orsectsubtitle_xformwas not enabled.title_strippedstripped stringThetitlefield, but with non-escaping markup removedsubtitle_strippedstripped string ornullThesubtitlefield, but with non-escaping markup removedidslist of stringsA list of all IDs assigned to the parsedsectionnode.classeslist of stringsA list of classes attached to the parsedsectionnode.subtitle_idslist of stringsA list of all IDs assigned to the section subtitle, or the empty list
if the section does not have a subtitle.subtitle_classeslist of stringsA list of classes attached to the section subtitle, or the empty list
if the section does not have a subtitle.toc_backrefstring ornullIf this section is listed in a table of contents with backlinks, this
field will equal the ID of the location in the table of contents that
the backlink should point to; otherwise, it will benull.  If the
section is listed in more than one table of contents with backlinks,
which value ends up in this field is Docutils-implementation-defined.numberstripped string ornullThe section number as generated by thesectnum::directive, ornullif no section number was generated for the section.depthintegerThe depth of the section: 1 for a top-level section, 2 for a
subsection, 3 for a sub-subsection, etc.bodyrendered stringThe rendered contents of the section.  This field is only present ifsplit_section_levelis equal to the section depth.introrendered stringThe rendered content of the section before the first subsection.  This
field is only present ifsplit_section_levelis negative or
greater than the section depth.sectionslist of objectsA list of the top-level subsections of this section, each one
represented as an object with the same schema ascontent.sections[].  This field is only present ifsplit_section_levelis negative or greater than the section depth.trailing_transitionobject ornullIf there is a transition between this section and the next one, this
field will be an object with the fieldsids(a list of IDs
assigned to the transition) andclasses(a list of classes
assigned to the transition); otherwise, this field will benull.
Note that, in a parsed document tree, inter-section transitions only
ever occur between consecutive sections of the same depth.Note: As far as the author of this library can determine, it is not
possible for a reStructuredText document to produce a doctree in which the
document title, docinfo, header, footer, abstract, dedication, or section
title nodes have any IDs or classes, nor for any docinfo field nodes to have
any IDs.rst2jsonthus does not output any fields for such values.metaobjectA dictionary of data about the input document and therst2jsonprocess,
containing the following fields:formatstringThe name of the target markup format:"html4","html5","latex", or"xelatex".split_section_levelintegerThe value set for thesplit_section_leveloption (See
“Configuration Options”).  Negative values are converted to -1.titlestripped string ornullThe document’s metadata title.  By default, this is equal tocontent.title_stripped, but it can be overridden by atitle::directive or thetitleconfiguration option.  If none of these are
set, the field isnull.Note that, if the title is set via thetitle::directive ortitleconfiguration option, any reStructuredText markup in it will not be
processed (though characters special to the output format will still be
escaped).  For example, including.. title:: *War & Peace*in your
input document will (when outputting HTML) produce ameta.titlevalue
of"*War &amp; Peace*", with the asterisks left as-is and the
ampersand escaped.sourcestripped stringThe name of/path to the input file.  If no name can be determined, then
this will be the empty string.languagestringThe language code for the document language, as set via thelanguage_codeconfiguration optiondocutils_versionstringThe version of Docutils used to produce the outputrst2json_versionstringThe version ofrst2jsonused to produce the outputgeneratorstripped stringA string of the form"rst2json {version}({url}),Docutils {version}({url})"htmlobjectA dictionary of strings to insert in the head of the final HTML document.
This object only appears in the output when the target format is HTML4 or
HTML5.  The fields of the dictionary are as follows:math_requiresrendered stringIf the input document contains anymath::directives or:math:roles, this is a string containing the appropriate markup to add to the
HTML document head in order to support them; if there are no such
directives or roles, this is the empty string.When set, the value of this field is determined by themath_outputconfiguration option.  When set tohtml, it is either a<link>tag or a<style>block (as determined by theembed_stylesheetconfiguration option) enabling the stylesheet passed as the option
argument; when set tomathjax, it is a<script>tag pointing to
the path or URL passed as the option argument.  Whenmath_outputismathmlorlatex, themath_requiresfield is the empty string,
as nothing needs to be added to the HTML document.meta_tagsrendered stringA string containing any & all<meta>tags added to the document with
themeta::directive.  If nometa::directives were given, this
is the empty string.latexobjectA dictionary of strings to insert in the preamble of the final (Xe)LaTeX
document.  This object only appears in the output when the target format is
LaTeX or XeLaTeX.  The fields of the dictionary are as follows:languagestringThe name of the document language (set via thelanguage_codeconfiguration option) in a form recognized by Babel.  If Docutils does
not recognize the language, this will be the empty string.  Note that,
when the language is not English,latex.requirementswill already
contain the appropriate\usepackage[LANGUAGE]{babel}command; the
purpose of this field is to be able to set the language in the document
options.requirementsrendered stringRequired packages and setup, mostly consisting of\includepackagecommands needed for the markup incontent.body.  In a templated
(Xe)LaTeX document, this should be placed near the beginning of the
preamble.fallbacksrendered stringFallback definitions (declared with\providecommand*) for the various
custom commands that Docutils uses in the body.  These definitions can be
overridden by defining commands of the same name in the preamble beforelatex.fallbacksoccurs.  In a templated (Xe)LaTeX document, this
should be placed afterlatex.requirementsand after any custom
preamble commands.pdfsetuprendered stringInclusion & setup of thehyperrefpackage.  In a templated (Xe)LaTeX
document, this should be placed at the end of the preamble.system_messageslist of objectsA list of system messages generated during processing of the input document.
Normally, system messages are embedded in the output in addition to being
reported to stderr, butrst2jsonremoves them from the body and places
them in this list.  Each system message is represented as an object with the
following fields:levelintegerThe system message level as an integer from 0 (least severe) through 4
(most severe)typestringThe name of the system message level.  The names and corresponding
integer values of the system message levels are as follows:typelevelDEBUG0INFO1WARNING2ERROR3SEVERE4sourcestripped stringThe name of the input file in which the message was generated.  If no
name can be determined, then this will be the empty string.lineinteger ornullThe line of the input file at which the message was generated, ornullif it cannot be determinedbodyrendered stringThe message itselfidslist of stringsThe IDs of thesystem_messagenode.  If the parsed document tree
contains aproblematicnode enclosing the markup that generated the
system message, the renderedproblematicnode will link to this
system message by targeting an ID inids.If the system message is included in the templated document, the IDs
should be attached to the structure using HTML’sidattribute or
(Xe)LaTeX’s\labelcommand.backrefslist of stringsIf the parsed document tree contains aproblematicnode enclosing the
markup that generated the system message,backrefswill contain the
renderedproblematicnode’s IDs, usable for creating an
intra-document link.id_sectionsobjectThis object only appears in the output whensplit_section_level(See
“Configuration Options”) is not 0.  It is a map in which each key is an
ID appearing in the rendered document body and the corresponding value is
the first ID of the deepest split-section object in which the key ID occurs.
IDs of inter-section transitions are mapped to the ID of the section in
whosetrailing_transitionfield they are stored.  IDs that appear incontent.introare mapped to the special string"$intro".  IDs of
top-level sections are not included as keys in this map, but IDs of deeper
sections are.This field can be used to rewrite inter-document links when the output is
used to create a separate templated document for each section.As an example, consider the following document:Section 1=========.._foo:Lorem ipsum yadda yadda yadda.Section 2========='Twas brillig, and the slithy toves did gyre and gimble in the wabe.Section 2.1-----------.._bar:All mimsy were the borogoves, and the mome raths outgrabe.Section 2.1.1~~~~~~~~~~~~~Beware the Jabberwock, my son!If this is processed with asplit_section_levelof 1, thenid_sectionswill look like:{"foo":"section-1","section-2-1":"section-2","bar":"section-2","section-2-1-1":"section-2"}If this is processed with asplit_section_levelof 2, thenid_sectionswill look like:{"foo":"section-1","section-2-1":"section-2","bar":"section-2-1","section-2-1-1":"section-2-1"}Increasingsplit_section_levelbeyond this point or making it negative
will not have any further effect.