diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000000..69fe55ecfa9aa --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/markdown2rst.py b/docs/markdown2rst.py new file mode 100644 index 0000000000000..cc488298f9f90 --- /dev/null +++ b/docs/markdown2rst.py @@ -0,0 +1,720 @@ +#!/usr/bin/env python3 +""" + markdown to rst +""" +# -*- coding: utf-8 -*- + +from __future__ import print_function, unicode_literals +import os +import os.path +import re +import sys +from argparse import ArgumentParser, Namespace + +from docutils import statemachine, nodes, io, utils +from docutils.parsers import rst +from docutils.core import ErrorString +from docutils.utils import SafeString, column_width +import mistune + +if sys.version_info < (3, ): + from codecs import open as _open + from urlparse import urlparse +else: + _open = open + from urllib.parse import urlparse + +__version__ = '0.2.1' +_is_sphinx = False +prolog = '''\ +.. role:: raw-html-m2r(raw) + :format: html + +''' + +# for command-line use +parser = ArgumentParser() +options = Namespace() +parser.add_argument( + 'input_file', nargs='*', help='files to convert to reST format') +parser.add_argument( + '--overwrite', + action='store_true', + default=False, + help='overwrite output file without confirmaion') +parser.add_argument( + '--dry-run', + action='store_true', + default=False, + help='print conversion result and not save output file') +parser.add_argument( + '--no-underscore-emphasis', + action='store_true', + default=False, + help='do not use underscore (_) for emphasis') +parser.add_argument( + '--parse-relative-links', + action='store_true', + default=False, + help='parse relative links into ref or doc directives') +parser.add_argument( + '--anonymous-references', + action='store_true', + default=False, + help='use anonymous references in generated rst') +parser.add_argument( + '--disable-inline-math', + action='store_true', + default=False, + help='disable parsing inline math') + + +def parse_options(): + """parse_options""" + parser.parse_known_args(namespace=options) + + +class RestBlockGrammar(mistune.BlockGrammar): + """RestBlockGrammar""" + directive = re.compile( + r'^( *\.\..*?)\n(?=\S)', + re.DOTALL | re.MULTILINE, ) + oneline_directive = re.compile( + r'^( *\.\..*?)$', + re.DOTALL | re.MULTILINE, ) + rest_code_block = re.compile( + r'^::\s*$', + re.DOTALL | re.MULTILINE, ) + + +class RestBlockLexer(mistune.BlockLexer): + """RestBlockLexer""" + grammar_class = RestBlockGrammar + default_rules = [ + 'directive', + 'oneline_directive', + 'rest_code_block', + ] + mistune.BlockLexer.default_rules + + def parse_directive(self, m): + """parse_directive""" + self.tokens.append({ + 'type': 'directive', + 'text': m.group(1), + }) + + def parse_oneline_directive(self, m): + """parse_oneline_directive""" + # reuse directive output + self.tokens.append({ + 'type': 'directive', + 'text': m.group(1), + }) + + def parse_rest_code_block(self, m): + """parse_rest_code_block""" + self.tokens.append({'type': 'rest_code_block', }) + + +class RestInlineGrammar(mistune.InlineGrammar): + """RestInlineGrammar""" + image_link = re.compile( + r'\[!\[(?P.*?)\]\((?P.*?)\).*?\]\((?P.*?)\)') + rest_role = re.compile(r':.*?:`.*?`|`[^`]+`:.*?:') + rest_link = re.compile(r'`[^`]*?`_') + inline_math = re.compile(r'.*\$(.*)?\$') + eol_literal_marker = re.compile(r'(\s+)?::\s*$') + # add colon and space as special text + text = re.compile(r'^[\s\S]+?(?=[\\[\s\S]+?)\1{2}(?!\1)') + # _word_ or *word* + emphasis = re.compile(r'^\b_((?:__|[^_])+?)_\b' # _word_ + r'|' + r'^\*(?P(?:\*\*|[^\*])+?)\*(?!\*)' # *word* + ) + + def no_underscore_emphasis(self): + """no_underscore_emphasis""" + self.double_emphasis = re.compile( + r'^\*{2}(?P[\s\S]+?)\*{2}(?!\*)' # **word** + ) + self.emphasis = re.compile( + r'^\*(?P(?:\*\*|[^\*])+?)\*(?!\*)' # *word* + ) + + +class RestInlineLexer(mistune.InlineLexer): + """RestInlineLexer""" + grammar_class = RestInlineGrammar + default_rules = [ + 'image_link', + 'rest_role', + 'rest_link', + 'eol_literal_marker', + ] + mistune.InlineLexer.default_rules + + def __init__(self, *args, **kwargs): + no_underscore_emphasis = kwargs.pop('no_underscore_emphasis', False) + disable_inline_math = kwargs.pop('disable_inline_math', False) + super(RestInlineLexer, self).__init__(*args, **kwargs) + if not _is_sphinx: + parse_options() + if no_underscore_emphasis or getattr(options, 'no_underscore_emphasis', + False): + self.rules.no_underscore_emphasis() + inline_maths = 'inline_math' in self.default_rules + if disable_inline_math or getattr(options, 'disable_inline_math', + False): + if inline_maths: + self.default_rules.remove('inline_math') + elif not inline_maths: + self.default_rules.insert(0, 'inline_math') + + def output_double_emphasis(self, m): + """output_double_emphasis""" + # may include code span + text = self.output(m.group('text')) + return self.renderer.double_emphasis(text) + + def output_emphasis(self, m): + """output_emphasis""" + # may include code span + text = self.output(m.group('text') or m.group(1)) + return self.renderer.emphasis(text) + + def output_image_link(self, m): + """Pass through rest role.""" + return self.renderer.image_link( + m.group('url'), m.group('target'), m.group('alt')) + + def output_rest_role(self, m): + """Pass through rest role.""" + return self.renderer.rest_role(m.group(0)) + + def output_rest_link(self, m): + """Pass through rest link.""" + return self.renderer.rest_link(m.group(0)) + + def output_inline_math(self, m): + """Pass through rest link.""" + return self.renderer.inline_math(m.group(0)) + + def output_eol_literal_marker(self, m): + """Pass through rest link.""" + marker = ':' if m.group(1) is None else '' + return self.renderer.eol_literal_marker(marker) + + +class RestRenderer(mistune.Renderer): + """RestRenderer""" + _include_raw_html = False + list_indent_re = re.compile(r'^(\s*(#\.|\*)\s)') + indent = ' ' * 3 + list_marker = '{#__rest_list_mark__#}' + hmarks = { + 1: '=', + 2: '-', + 3: '^', + 4: '~', + 5: '"', + 6: '#', + } + + def __init__(self, *args, **kwargs): + self.parse_relative_links = kwargs.pop('parse_relative_links', False) + self.anonymous_references = kwargs.pop('anonymous_references', False) + super(RestRenderer, self).__init__(*args, **kwargs) + if not _is_sphinx: + parse_options() + if getattr(options, 'parse_relative_links', False): + self.parse_relative_links = options.parse_relative_links + if getattr(options, 'anonymous_references', False): + self.anonymous_references = options.anonymous_references + + def _indent_block(self, block): + return '\n'.join(self.indent + line if line else '' + for line in block.splitlines()) + + def _raw_html(self, html): + self._include_raw_html = True + return '\ :raw-html-m2r:`{}`\ '.format(html) + + def block_code(self, code, lang=None): + """block_code""" + if lang == 'math': + first_line = '\n.. math::\n\n' + elif lang: + first_line = '\n.. code-block:: {}\n\n'.format(lang) + elif _is_sphinx: + first_line = '\n.. code-block:: guess\n\n' + else: + first_line = '\n.. code-block::\n\n' + return first_line + self._indent_block(code) + '\n' + + def block_quote(self, text): + """block_quote""" + # text includes some empty line + return '\n..\n\n{}\n\n'.format(self._indent_block(text.strip('\n'))) + + def block_html(self, html): + """Rendering block level pure html content. + + :param html: text content of the html snippet. + """ + return '\n\n.. raw:: html\n\n' + self._indent_block(html) + '\n\n' + + def header(self, text, level, raw=None): + """Rendering header/heading tags like ``

`` ``

``. + + :param text: rendered text content for the header. + :param level: a number for the header level, for example: 1. + :param raw: raw text content of the header. + """ + return '\n{0}\n{1}\n'.format(text, + self.hmarks[level] * column_width(text)) + + def hrule(self): + """Rendering method for ``
`` tag.""" + return '\n----\n' + + def list(self, body, ordered=True): + """Rendering list tags like ``
    `` and ``
      ``. + + :param body: body contents of the list. + :param ordered: whether this list is ordered or not. + """ + mark = '#. ' if ordered else '* ' + lines = body.splitlines() + for i, line in enumerate(lines): + if line and not line.startswith(self.list_marker): + lines[i] = ' ' * len(mark) + line + return '\n{}\n'.format('\n'.join(lines)).replace(self.list_marker, + mark) + + def list_item(self, text): + """Rendering list item snippet. Like ``
    1. ``.""" + return '\n' + self.list_marker + text + + def paragraph(self, text): + """Rendering paragraph tags. Like ``

      ``.""" + return '\n' + text + '\n' + + def table(self, header, body): + """Rendering table element. Wrap header and body in it. + + :param header: header part of the table. + :param body: body part of the table. + """ + table = '\n.. list-table::\n' + if header and not header.isspace(): + table = (table + self.indent + ':header-rows: 1\n\n' + + self._indent_block(header) + '\n') + else: + table = table + '\n' + table = table + self._indent_block(body) + '\n\n' + return table + + def table_row(self, content): + """Rendering a table row. Like ````. + + :param content: content of current table row. + """ + contents = content.splitlines() + if not contents: + return '' + clist = ['* ' + contents[0]] + if len(contents) > 1: + for c in contents[1:]: + clist.append(' ' + c) + return '\n'.join(clist) + '\n' + + def table_cell(self, content, **flags): + """Rendering a table cell. Like ```` ````. + + :param content: content of current table cell. + :param header: whether this is header or not. + :param align: align of current table cell. + """ + return '- ' + content + '\n' + + def double_emphasis(self, text): + """Rendering **strong** text. + + :param text: text content for emphasis. + """ + return '\ **{}**\ '.format(text) + + def emphasis(self, text): + """Rendering *emphasis* text. + + :param text: text content for emphasis. + """ + return '\ *{}*\ '.format(text) + + def codespan(self, text): + """Rendering inline `code` text. + + :param text: text content for inline code. + """ + if '``' not in text: + return '\ ``{}``\ '.format(text) + else: + # actually, docutils split spaces in literal + return self._raw_html('' + '{}' + ''.format( + text.replace('`', '`'))) + + def linebreak(self): + """Rendering line break like ``
      ``.""" + if self.options.get('use_xhtml'): + return self._raw_html('
      ') + '\n' + return self._raw_html('
      ') + '\n' + + def strikethrough(self, text): + """Rendering ~~strikethrough~~ text. + + :param text: text content for strikethrough. + """ + return self._raw_html('{}'.format(text)) + + def text(self, text): + """Rendering unformatted text. + + :param text: text content. + """ + return text + + def autolink(self, link, is_email=False): + """Rendering a given link or email address. + + :param link: link content or email address. + :param is_email: whether this is an email or not. + """ + return link + + def link(self, link, title, text): + """Rendering a given link with content and title. + + :param link: href link for ```` tag. + :param title: title content for `title` attribute. + :param text: text content for description. + """ + if self.anonymous_references: + underscore = '__' + else: + underscore = '_' + if title: + return self._raw_html( + '{text}'.format( + link=link, title=title, text=text)) + if not self.parse_relative_links: + return '\ `{text} <{target}>`{underscore}\ '.format( + target=link, text=text, underscore=underscore) + else: + url_info = urlparse(link) + if url_info.scheme: + return '\ `{text} <{target}>`{underscore}\ '.format( + target=link, text=text, underscore=underscore) + else: + link_type = 'doc' + anchor = url_info.fragment + if url_info.fragment: + if url_info.path: + # Can't link to anchors via doc directive. + anchor = '' + else: + # Example: [text](#anchor) + link_type = 'ref' + doc_link = '{doc_name}{anchor}'.format( + # splittext approach works whether or not path is set. It + # will return an empty string if unset, which leads to + # anchor only ref. + doc_name=os.path.splitext(url_info.path)[0], + anchor=anchor) + return '\ :{link_type}:`{text} <{doc_link}>`\ '.format( + link_type=link_type, doc_link=doc_link, text=text) + + def image(self, src, title, text): + """Rendering a image with title and text. + + :param src: source link of the image. + :param title: title text of the image. + :param text: alt text of the image. + """ + # rst does not support title option + # and I couldn't find title attribute in HTML standard + return '\n'.join([ + '', + '.. image:: {}'.format(src), + ' :target: {}'.format(src), + ' :alt: {}'.format(text), + '', + ]) + + def inline_html(self, html): + """Rendering span level pure html content. + + :param html: text content of the html snippet. + """ + return self._raw_html(html) + + def newline(self): + """Rendering newline element.""" + return '' + + def footnote_ref(self, key, index): + """Rendering the ref anchor of a footnote. + + :param key: identity key for the footnote. + :param index: the index count of current footnote. + """ + return '\ [#fn-{}]_\ '.format(key) + + def footnote_item(self, key, text): + """Rendering a footnote item. + + :param key: identity key for the footnote. + :param text: text content of the footnote. + """ + return '.. [#fn-{0}] {1}\n'.format(key, text.strip()) + + def footnotes(self, text): + """Wrapper for all footnotes. + + :param text: contents of all footnotes. + """ + if text: + return '\n\n' + text + else: + return '' + + """Below outputs are for rst.""" + + def image_link(self, url, target, alt): + """image_link""" + return '\n'.join([ + '', + '.. image:: {}'.format(url), + ' :target: {}'.format(target), + ' :alt: {}'.format(alt), + '', + ]) + + def rest_role(self, text): + """rest_role""" + return text + + def rest_link(self, text): + """rest_link""" + return text + + def inline_math(self, math): + """Extension of recommonmark""" + return re.sub(r'\$(.*?)\$', + lambda x: '\ :math:`{}`\ '.format(x.group(1)), math) + + def eol_literal_marker(self, marker): + """Extension of recommonmark""" + return marker + + def directive(self, text): + """directive""" + return '\n' + text + '\n' + + def rest_code_block(self): + """rest_code_block""" + return '\n\n' + + +class M2R(mistune.Markdown): + """M2R""" + + def __init__(self, + renderer=None, + inline=RestInlineLexer, + block=RestBlockLexer, + **kwargs): + if renderer is None: + renderer = RestRenderer(**kwargs) + super(M2R, self).__init__( + renderer, inline=inline, block=block, **kwargs) + + def parse(self, text): + """parse""" + output = super(M2R, self).parse(text) + return self.post_process(output) + + def output_directive(self): + """output_directive""" + return self.renderer.directive(self.token['text']) + + def output_rest_code_block(self): + """output_rest_code_block""" + return self.renderer.rest_code_block() + + def post_process(self, text): + """post_process""" + output = (text.replace('\\ \n', '\n').replace('\n\\ ', '\n') + .replace(' \\ ', ' ').replace('\\ ', ' ') + .replace('\\ .', '.')) + if self.renderer._include_raw_html: + return prolog + output + else: + return output + + +class M2RParser(rst.Parser, object): + """M2RParser""" + # Explicitly tell supported formats to sphinx + supported = ('markdown', 'md', 'mkd') + + def parse(self, inputstrings, document): + """parse""" + if isinstance(inputstrings, statemachine.StringList): + inputstring = '\n'.join(inputstrings) + else: + inputstring = inputstrings + config = document.settings.env.config + converter = M2R(no_underscore_emphasis=config.no_underscore_emphasis, + parse_relative_links=config.m2r_parse_relative_links, + anonymous_references=config.m2r_anonymous_references, + disable_inline_math=config.m2r_disable_inline_math) + super(M2RParser, self).parse(converter(inputstring), document) + + +class MdInclude(rst.Directive): + """Directive class to include markdown in sphinx. + + Load a file and convert it to rst and insert as a node. Currently + directive-specific options are not implemented. + """ + required_arguments = 1 + optional_arguments = 0 + option_spec = { + 'start-line': int, + 'end-line': int, + } + + def run(self): + """Most of this method is from ``docutils.parser.rst.Directive``. + + docutils version: 0.12 + """ + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + source = self.state_machine.input_lines.source( + self.lineno - self.state_machine.input_offset - 1) + source_dir = os.path.dirname(os.path.abspath(source)) + path = rst.directives.path(self.arguments[0]) + path = os.path.normpath(os.path.join(source_dir, path)) + path = utils.relative_path(None, path) + path = nodes.reprunicode(path) + + # get options (currently not use directive-specific options) + encoding = self.options.get( + 'encoding', self.state.document.settings.input_encoding) + e_handler = self.state.document.settings.input_encoding_error_handler + tab_width = self.options.get('tab-width', + self.state.document.settings.tab_width) + + # open the including file + try: + self.state.document.settings.record_dependencies.add(path) + include_file = io.FileInput( + source_path=path, encoding=encoding, error_handler=e_handler) + except UnicodeEncodeError as error: + raise self.severe('Problems with "%s" directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % + (self.name, SafeString(path))) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + + # read from the file + startline = self.options.get('start-line', None) + endline = self.options.get('end-line', None) + try: + if startline or (endline is not None): + lines = include_file.readlines() + rawtext = ''.join(lines[startline:endline]) + else: + rawtext = include_file.read() + except UnicodeError as error: + raise self.severe('Problem with "%s" directive:\n%s' % + (self.name, ErrorString(error))) + + config = self.state.document.settings.env.config + converter = M2R(no_underscore_emphasis=config.no_underscore_emphasis, + parse_relative_links=config.m2r_parse_relative_links, + anonymous_references=config.m2r_anonymous_references, + disable_inline_math=config.m2r_disable_inline_math) + include_lines = statemachine.string2lines( + converter(rawtext), tab_width, convert_whitespace=True) + self.state_machine.insert_input(include_lines, path) + return [] + + +def setup(app): + """When used for sphinx extension.""" + global _is_sphinx + _is_sphinx = True + app.add_config_value('no_underscore_emphasis', False, 'env') + app.add_config_value('m2r_parse_relative_links', False, 'env') + app.add_config_value('m2r_anonymous_references', False, 'env') + app.add_config_value('m2r_disable_inline_math', False, 'env') + app.add_source_parser('.md', M2RParser) + app.add_directive('mdinclude', MdInclude) + metadata = dict( + version=__version__, + parallel_read_safe=True, + parallel_write_safe=True, ) + return metadata + + +def convert(text, **kwargs): + """convert""" + return M2R(**kwargs)(text) + + +def parse_from_file(file, encoding='utf-8', **kwargs): + """parse_from_file""" + if not os.path.exists(file): + raise OSError('No such file exists: {}'.format(file)) + with _open(file, encoding=encoding) as f: + src = f.read() + output = convert(src, **kwargs) + return output + + +def save_to_file(file, src, encoding='utf-8', **kwargs): + """save_to_file""" + target = os.path.splitext(file)[0] + '.rst' + if not options.overwrite and os.path.exists(target): + confirm = input('{} already exists. overwrite it? [y/n]: '.format( + target)) + if confirm.upper() not in ('Y', 'YES'): + print('skip {}'.format(file)) + return + with _open(target, 'w', encoding=encoding) as f: + f.write(src) + + +def main(): + """main""" + parse_options() # parse cli options + if not options.input_file: + parser.print_help() + parser.exit(0) + for file in options.input_file: + output = parse_from_file(file) + if options.dry_run: + print(output) + else: + save_to_file(file, output) + + +if __name__ == '__main__': + main() diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000000000..415f3add50bb6 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,173 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = u'PLSC' +copyright = u'2020, Paddle Authors' +author = u'Paddle Authors' + +# The short X.Y version +version = u'' +# The full version, including alpha/beta/rc tags +release = u'' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = u'zh' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PLSCdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'PLSC.tex', u'PLSC Documentation', + u'Paddle Authors', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'plsc', u'PLSC Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'PLSC', u'PLSC Documentation', + author, 'PLSC', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000000000..baa75eed1b8bb --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. PLSC documentation master file, created by + sphinx-quickstart on Thu Feb 27 10:54:35 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to PLSC's documentation! +================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`