module sphinxext.sphinx_md_builder

Short summary

module pyquickhelper.sphinxext.sphinx_md_builder

Defines a sphinx extension to output the documentation in Markdown or MD. It is inspired from restbuilder. I replicate its license here:

Copyright (c) 2012-2013 by Freek Dijkstra <software@macfreek.nl>.
Some rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

source on GitHub

Classes

class	truncated documentation
MdBuilder	Defines a MD builder.
MdTranslator	Defines a MD translator.
MdWriter	Defines a MD writer.

Functions

function	truncated documentation
setup	Initializes the MD builder.

Static Methods

staticmethod	truncated documentation
_make_depart_admonition

Methods

method	truncated documentation
__init__	Constructor, add a logger.
__init__
__init__
_visit_admonition
_visit_admonition
_visit_admonition
_visit_admonition
_visit_admonition
_visit_admonition
_visit_admonition
_visit_admonition
_visit_admonition
_visit_admonition
add_text
depart_abbreviation
depart_admonition
depart_admonition
depart_admonition
depart_admonition
depart_admonition
depart_admonition
depart_admonition
depart_admonition
depart_admonition
depart_admonition
depart_attribution
depart_bullet_list
depart_caption
depart_centered
depart_citation
depart_classifier
depart_CodeNode
depart_compact_paragraph
depart_compound
depart_definition
depart_definition_list
depart_definition_list_item
depart_desc
depart_desc_addname
depart_desc_annotation
depart_desc_content
depart_desc_name
depart_desc_optional
depart_desc_parameterlist
depart_desc_returns
depart_desc_signature
depart_desc_type
depart_description
depart_doctest_block
depart_document
depart_download_reference
depart_downloadlink_node
depart_emphasis
depart_entry
depart_enumerated_list
depart_field
depart_field_body
depart_field_list
depart_field_name
depart_figure
depart_footnote
depart_generated
depart_glossary
depart_hlist
depart_hlistcol
depart_image
depart_imgsgnode
depart_inheritance_diagram
depart_inline
depart_issue
depart_line
depart_line_block
depart_list_item
depart_literal
depart_literal_block
depart_literal_emphasis
depart_only
depart_option
depart_option_argument
depart_option_group
depart_option_list
depart_option_list_item
depart_option_string
depart_paragraph
depart_pending_xref
depart_problematic
depart_refcount
depart_reference
depart_row
depart_rubric
depart_runpythonthis_node
depart_section
depart_seealso
depart_simpleimage
depart_strong
depart_subscript
depart_subtitle
depart_superscript
depart_table
depart_tbody
depart_term
depart_Text
depart_tgroup
depart_thead
depart_title
depart_title_reference
depart_todo_node
depart_topic
depart_topic
end_state
eval_expr
finish
get_outdated_docs	Return an iterable of input files that are outdated. This method is taken from TextBuilder.get_outdated_docs() …
get_outfilename	Overwrite get_target_uri to control file names.
get_target_uri
handle_page
init	Load necessary templates and perform initialization.
log_unknown
new_state
prepare_writing
translate
unknown_visit
visit_abbreviation
visit_acks
visit_admonition
visit_attribution
visit_bullet_list
visit_caption
visit_centered
visit_citation
visit_citation_reference
visit_classifier
visit_CodeNode
visit_colspec
visit_comment
visit_compact_paragraph
visit_compound
visit_definition
visit_definition_list
visit_definition_list_item
visit_desc
visit_desc_addname
visit_desc_annotation
visit_desc_content
visit_desc_name
visit_desc_optional
visit_desc_parameter
visit_desc_parameterlist
visit_desc_returns
visit_desc_signature
visit_desc_type
visit_description
visit_doctest_block
visit_document
visit_download_reference
visit_downloadlink_node
visit_emphasis
visit_entry
visit_enumerated_list
visit_field
visit_field_body
visit_field_list
visit_field_name
visit_figure
visit_footnote
visit_footnote_reference
visit_generated
visit_glossary
visit_highlightlang
visit_hlist
visit_hlistcol
visit_image
visit_imgsgnode
visit_index
visit_inheritance_diagram
visit_inline
visit_issue
visit_label
visit_line
visit_line_block
visit_list_item
visit_literal
visit_literal_block
visit_literal_emphasis
visit_meta
visit_only
visit_option
visit_option_argument
visit_option_group
visit_option_list
visit_option_list_item
visit_option_string
visit_paragraph
visit_pending_xref
visit_problematic
visit_productionlist
visit_raw
visit_refcount
visit_reference
visit_row
visit_rubric
visit_runpythonthis_node
visit_section
visit_seealso
visit_simpleimage
visit_strong
visit_subscript
visit_substitution_definition
visit_subtitle
visit_superscript
visit_system_message
visit_table
visit_tabular_col_spec
visit_target
visit_tbody
visit_term
visit_termsep
visit_Text
visit_tgroup
visit_thead
visit_title
visit_title_reference
visit_todo_node
visit_topic
visit_topic
visit_transition
wrap
write_doc

Documentation

Defines a sphinx extension to output the documentation in Markdown or MD. It is inspired from restbuilder. I replicate its license here:

Copyright (c) 2012-2013 by Freek Dijkstra <software@macfreek.nl>.
Some rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

source on GitHub

class pyquickhelper.sphinxext.sphinx_md_builder.MdBuilder(*args, **kwargs)

Bases: Builder

Defines a MD builder.

source on GitHub

Constructor, add a logger.

source on GitHub

__init__(*args, **kwargs)

Constructor, add a logger.

source on GitHub

default_translator_class

alias of MdTranslator

finish()

Finish the building process.

The default implementation does nothing.

format = 'md'

The builder’s output format, or ‘’ if no document output is produced.

get_outdated_docs()

Return an iterable of input files that are outdated. This method is taken from TextBuilder.get_outdated_docs() with minor changes to support (confval, md_file_transform)).

source on GitHub

get_outfilename(pagename)

Overwrite get_target_uri to control file names.

source on GitHub

get_target_uri(docname, typ=None)

Return the target URI for a document name.

typ can be used to qualify the link characteristic for individual builders.

init()

Load necessary templates and perform initialization.

source on GitHub

name = 'md'

The builder’s name, for the -b command line option.

prepare_writing(docnames)

A place where you can add logic before write_doc() is run

write_doc(docname, doctree)

Where you actually write something to the filesystem.

class pyquickhelper.sphinxext.sphinx_md_builder.MdTranslator(document, builder)

Bases: TextTranslator, CommonSphinxWriterHelpers

Defines a MD translator.

source on GitHub

__init__(document, builder)

_make_depart_admonition()

_visit_admonition(node)

unknown_visit(node)

Called when entering unknown Node types.

Raise an exception unless overridden.

class pyquickhelper.sphinxext.sphinx_md_builder.MdWriter(builder)

Bases: Writer

Defines a MD writer.

source on GitHub

__init__(builder)

output = None

Final translated form of document (Unicode string for text, binary string for other forms); set by translate.

settings_defaults = {}

A dictionary of defaults for settings not in settings_spec (internal settings, intended to be inaccessible by command-line and config file). Override in subclasses.

settings_spec = ('No options here.', '', ())

Runtime settings specification. Override in subclasses.

Defines runtime settings and associated command-line options, as used by docutils.frontend.OptionParser. This is a tuple of:

• Option group title (string or None which implies no group, just a list of single options).

• Description (string or None).

• A sequence of option tuples. Each consists of:

  • Help text (string)

  • List of option strings (e.g. ['-Q', '--quux']).

  • Dictionary of keyword arguments sent to the OptionParser/OptionGroup add_option method.

    Runtime setting names are derived implicitly from long option names (’–a-setting’ becomes settings.a_setting) or explicitly from the ‘dest’ keyword argument.

    Most settings will also have a ‘validator’ keyword & function. The validator function validates setting values (from configuration files and command-line option arguments) and converts them to appropriate types. For example, the docutils.frontend.validate_boolean function, required by all boolean settings, converts true values (‘1’, ‘on’, ‘yes’, and ‘true’) to 1 and false values (‘0’, ‘off’, ‘no’, ‘false’, and ‘’) to 0. Validators need only be set once per setting. See the docutils.frontend.validate_* functions.

    See the optparse docs for more details.

• More triples of group title, description, options, as many times as needed. Thus, settings_spec tuples can be simply concatenated.

supported = ('text',)

Names for this component. Override in subclasses.

translate()

Do final translation of self.document into self.output. Called from write. Override in subclasses.

Usually done with a docutils.nodes.NodeVisitor subclass, in combination with a call to docutils.nodes.Node.walk() or docutils.nodes.Node.walkabout(). The NodeVisitor subclass must support all standard elements (listed in docutils.nodes.node_class_names) and possibly non-standard elements used by the current Reader as well.

translator_class

alias of MdTranslator

pyquickhelper.sphinxext.sphinx_md_builder.setup(app)

Initializes the MD builder.

source on GitHub