diff options
Diffstat (limited to 'tests/roots/test-root')
42 files changed, 1698 insertions, 0 deletions
diff --git a/tests/roots/test-root/Makefile b/tests/roots/test-root/Makefile new file mode 100644 index 0000000..85a93bc --- /dev/null +++ b/tests/roots/test-root/Makefile @@ -0,0 +1,67 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build + +# Internal variables. +ALLSPHINXOPTS = -d _build/doctrees $(SPHINXOPTS) . + +.PHONY: help clean html web pickle htmlhelp latex changes linkcheck + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " pickle to make pickle files (usable by e.g. sphinx-web)" + @echo " htmlhelp to make HTML files and an HTML help project" + @echo " latex to make LaTeX files" + @echo " changes to make an overview over all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + +clean: + rm -rf _build/* + +html: + mkdir -p _build/html _build/doctrees + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html + @echo + @echo "Build finished. The HTML pages are in _build/html." + +pickle: + mkdir -p _build/pickle _build/doctrees + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle + @echo + @echo "Build finished; now you can process the pickle files or run" + @echo " sphinx-web _build/pickle" + @echo "to start the sphinx-web server." + +web: pickle + +htmlhelp: + mkdir -p _build/htmlhelp _build/doctrees + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in _build/htmlhelp." + +latex: + mkdir -p _build/latex _build/doctrees + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex + @echo + @echo "Build finished; the LaTeX files are in _build/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + mkdir -p _build/changes _build/doctrees + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes + @echo + @echo "The overview file is in _build/changes." + +linkcheck: + mkdir -p _build/linkcheck _build/doctrees + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in _build/linkcheck/output.txt." diff --git a/tests/roots/test-root/_templates/contentssb.html b/tests/roots/test-root/_templates/contentssb.html new file mode 100644 index 0000000..d0c276a --- /dev/null +++ b/tests/roots/test-root/_templates/contentssb.html @@ -0,0 +1,2 @@ +{# sidebar only for contents document #} +<h4>Contents sidebar</h4> diff --git a/tests/roots/test-root/_templates/customsb.html b/tests/roots/test-root/_templates/customsb.html new file mode 100644 index 0000000..0cd6735 --- /dev/null +++ b/tests/roots/test-root/_templates/customsb.html @@ -0,0 +1,4 @@ +{# custom sidebar template #} +<h4>Custom sidebar</h4> + +{{ toctree(titles_only=True, maxdepth=1) }} diff --git a/tests/roots/test-root/_templates/layout.html b/tests/roots/test-root/_templates/layout.html new file mode 100644 index 0000000..db685b0 --- /dev/null +++ b/tests/roots/test-root/_templates/layout.html @@ -0,0 +1,15 @@ +{% extends "!layout.html" %} + +{% block extrahead %} +{# html_context variable from conf.py #} +<meta name="hc" content="{{ hckey }}" /> +{# html_context variable from confoverrides (as if given on cmdline) #} +<meta name="hc_co" content="{{ hckey_co }}" /> +{{ super() }} +{% endblock %} + +{% block sidebartoc %} +{# display global TOC in addition to local TOC #} +{{ super() }} +{{ toctree(collapse=False, maxdepth=-1) }} +{% endblock %} diff --git a/tests/roots/test-root/autodoc.txt b/tests/roots/test-root/autodoc.txt new file mode 100644 index 0000000..959ab2d --- /dev/null +++ b/tests/roots/test-root/autodoc.txt @@ -0,0 +1,39 @@ +Autodoc tests +============= + +Just testing a few autodoc possibilities... + +.. automodule:: autodoc_target + :members: + +.. autofunction:: function + +.. autoclass:: Class + :inherited-members: + + Additional content. + +.. autoclass:: Outer + :members: Inner + +.. autoattribute:: Class.docattr + +.. autoexception:: CustomEx + :members: f + +.. autoclass:: CustomDict + :show-inheritance: + :members: + + +.. currentmodule:: autodoc_target + +.. autoclass:: InstAttCls + :members: + + All members (5 total) + +.. autoclass:: InstAttCls + :members: ca1, ia1 + + Specific members (2 total) diff --git a/tests/roots/test-root/autodoc_target.py b/tests/roots/test-root/autodoc_target.py new file mode 100644 index 0000000..59f6c74 --- /dev/null +++ b/tests/roots/test-root/autodoc_target.py @@ -0,0 +1,221 @@ +import enum +from io import StringIO + +__all__ = ['Class'] + +#: documentation for the integer +integer = 1 + + +def raises(exc, func, *args, **kwds): + """Raise AssertionError if ``func(*args, **kwds)`` does not raise *exc*.""" + pass + + +class CustomEx(Exception): + """My custom exception.""" + + def f(self): + """Exception method.""" + + +class CustomDataDescriptor: + """Descriptor class docstring.""" + + def __init__(self, doc): + self.__doc__ = doc + + def __get__(self, obj, type=None): + if obj is None: + return self + return 42 + + def meth(self): + """Function.""" + return "The Answer" + + +class CustomDataDescriptorMeta(type): + """Descriptor metaclass docstring.""" + + +class CustomDataDescriptor2(CustomDataDescriptor): + """Descriptor class with custom metaclass docstring.""" + __metaclass__ = CustomDataDescriptorMeta + + +def _funky_classmethod(name, b, c, d, docstring=None): + """Generates a classmethod for a class from a template by filling out + some arguments.""" + def template(cls, a, b, c, d=4, e=5, f=6): + return a, b, c, d, e, f + from functools import partial + function = partial(template, b=b, c=c, d=d) + function.__name__ = name + function.__doc__ = docstring + return classmethod(function) + + +class Base: + def inheritedmeth(self): + """Inherited function.""" + + +class Derived(Base): + def inheritedmeth(self): + # no docstring here + pass + + +class Class(Base): + """Class to document.""" + + descr = CustomDataDescriptor("Descriptor instance docstring.") + + def meth(self): + """Function.""" + + def undocmeth(self): + pass + + def skipmeth(self): + """Method that should be skipped.""" + + def excludemeth(self): + """Method that should be excluded.""" + + # should not be documented + skipattr = 'foo' + + #: should be documented -- süß + attr = 'bar' + + @property + def prop(self): + """Property.""" + + docattr = 'baz' + """should likewise be documented -- süß""" + + udocattr = 'quux' + """should be documented as well - süß""" + + # initialized to any class imported from another module + mdocattr = StringIO() + """should be documented as well - süß""" + + roger = _funky_classmethod("roger", 2, 3, 4) + + moore = _funky_classmethod("moore", 9, 8, 7, + docstring="moore(a, e, f) -> happiness") + + def __init__(self, arg): + self.inst_attr_inline = None #: an inline documented instance attr + #: a documented instance attribute + self.inst_attr_comment = None + self.inst_attr_string = None + """a documented instance attribute""" + self._private_inst_attr = None #: a private instance attribute + + def __special1__(self): + """documented special method""" + + def __special2__(self): + # undocumented special method + pass + + +class CustomDict(dict): + """Docstring.""" + + +def function(foo, *args, **kwds): + """ + Return spam. + """ + pass + + +class Outer: + """Foo""" + + class Inner: + """Foo""" + + def meth(self): + """Foo""" + + # should be documented as an alias + factory = dict + + +class DocstringSig: + def meth(self): + """meth(FOO, BAR=1) -> BAZ +First line of docstring + + rest of docstring + """ + + def meth2(self): + """First line, no signature + Second line followed by indentation:: + + indented line + """ + + @property + def prop1(self): + """DocstringSig.prop1(self) + First line of docstring + """ + return 123 + + @property + def prop2(self): + """First line of docstring + Second line of docstring + """ + return 456 + + +class StrRepr(str): + def __repr__(self): + return self + + +class AttCls: + a1 = StrRepr('hello\nworld') + a2 = None + + +class InstAttCls: + """Class with documented class and instance attributes.""" + + #: Doc comment for class attribute InstAttCls.ca1. + #: It can have multiple lines. + ca1 = 'a' + + ca2 = 'b' #: Doc comment for InstAttCls.ca2. One line only. + + ca3 = 'c' + """Docstring for class attribute InstAttCls.ca3.""" + + def __init__(self): + #: Doc comment for instance attribute InstAttCls.ia1 + self.ia1 = 'd' + + self.ia2 = 'e' + """Docstring for instance attribute InstAttCls.ia2.""" + + +class EnumCls(enum.Enum): + """ + this is enum class + """ + + #: doc for val1 + val1 = 12 + val2 = 23 #: doc for val2 + val3 = 34 + """doc for val3""" diff --git a/tests/roots/test-root/bom.txt b/tests/roots/test-root/bom.txt new file mode 100644 index 0000000..3fea824 --- /dev/null +++ b/tests/roots/test-root/bom.txt @@ -0,0 +1,5 @@ +File with UTF-8 BOM +=================== + +This file has a UTF-8 "BOM". + diff --git a/tests/roots/test-root/conf.py b/tests/roots/test-root/conf.py new file mode 100644 index 0000000..154d4d1 --- /dev/null +++ b/tests/roots/test-root/conf.py @@ -0,0 +1,148 @@ +import os +import sys + +from docutils import nodes +from docutils.parsers.rst import Directive + +from sphinx import addnodes + +sys.path.append(os.path.abspath('.')) + +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.extlinks'] + +jsmath_path = 'dummy.js' + +templates_path = ['_templates'] + +source_suffix = ['.txt', '.add', '.foo'] + +project = 'Sphinx <Tests>' +copyright = '1234-6789, copyright text credits' +# If this is changed, remember to update the versionchanges! +version = '0.6' +release = '0.6alpha1' +today_fmt = '%B %d, %Y' +exclude_patterns = ['_build', '**/excluded.*'] +keep_warnings = True +pygments_style = 'sphinx' +show_authors = True +numfig = True + +html_sidebars = {'**': ['localtoc.html', 'relations.html', 'sourcelink.html', + 'customsb.html', 'searchbox.html'], + 'index': ['contentssb.html', 'localtoc.html', 'globaltoc.html']} +html_last_updated_fmt = '%b %d, %Y' +html_context = {'hckey': 'hcval', 'hckey_co': 'wrong_hcval_co'} + +latex_additional_files = ['svgimg.svg'] +# some random pdf layout parameters to check they don't break build +latex_elements = { + 'sphinxsetup': """ + verbatimwithframe, + verbatimwrapslines, + verbatimforcewraps, + verbatimmaxoverfull=1, + verbatimmaxunderfull=5, + verbatimhintsturnover=true, + verbatimcontinuesalign=l, + VerbatimColor={RGB}{242,242,242}, + VerbatimBorderColor={RGB}{32,32,32}, + VerbatimHighlightColor={RGB}{200,200,200}, + pre_box-decoration-break=slice, + pre_border-top-left-radius=20pt, + pre_border-top-right-radius=0pt, + pre_border-bottom-right-radius=20pt, + pre_border-bottom-left-radius=0pt, + verbatimsep=1pt, + pre_padding=5pt,% alias to verbatimsep + pre_border-top-width=5pt, + pre_border-right-width=10pt, + pre_border-bottom-width=15pt, + pre_border-left-width=20pt, + pre_border-width=3pt,% overrides all previous four + verbatimborder=2pt,% alias to pre_border-width +% + shadowrule=1pt, + shadowsep=10pt, + shadowsize=10pt, + div.topic_border-width=2pt,% alias to shadowrule + div.topic_padding=6pt,% alias to shadowsep + div.topic_box-shadow=5pt,% overrides/alias shadowsize +% + noteBorderColor={RGB}{204,204,204}, + hintBorderColor={RGB}{204,204,204}, + importantBorderColor={RGB}{204,204,204}, + tipBorderColor={RGB}{204,204,204}, +% + noteborder=5pt, + hintborder=5pt, + importantborder=5pt, + tipborder=5pt, +% + warningborder=3pt, + cautionborder=3pt, + attentionborder=3pt, + errorborder=3pt, +% + dangerborder=3pt, + div.danger_border-width=10pt, + div.danger_background-TeXcolor={rgb}{0,1,0}, + div.danger_border-TeXcolor={rgb}{0,0,1}, + div.danger_box-shadow=20pt -20pt, + div.danger_box-shadow-TeXcolor={rgb}{0.5,0.5,0.5}, +% + warningBorderColor={RGB}{255,119,119}, + cautionBorderColor={RGB}{255,119,119}, + attentionBorderColor={RGB}{255,119,119}, + dangerBorderColor={RGB}{255,119,119}, + errorBorderColor={RGB}{255,119,119}, + warningBgColor={RGB}{255,238,238}, + cautionBgColor={RGB}{255,238,238}, + attentionBgColor={RGB}{255,238,238}, + dangerBgColor={RGB}{255,238,238}, + errorBgColor={RGB}{255,238,238}, +% + TableRowColorHeader={rgb}{0,1,0}, + TableRowColorOdd={rgb}{0.5,0,0}, + TableRowColorEven={rgb}{0.1,0.1,0.1}, +""", +} + +coverage_c_path = ['special/*.h'] +coverage_c_regexes = {'function': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'} + +extlinks = {'issue': ('http://bugs.python.org/issue%s', 'issue %s'), + 'pyurl': ('http://python.org/%s', None)} + +# modify tags from conf.py +tags.add('confpytag') + + +# -- extension API +def userdesc_parse(env, sig, signode): + x, y = sig.split(':') + signode += addnodes.desc_name(x, x) + signode += addnodes.desc_parameterlist() + signode[-1] += addnodes.desc_parameter(y, y) + return x + + +class ClassDirective(Directive): + option_spec = {'opt': lambda x: x} + + def run(self): + return [nodes.strong(text='from class: %s' % self.options['opt'])] + + +def setup(app): + import parsermod + + app.add_directive('clsdir', ClassDirective) + app.add_object_type('userdesc', 'userdescrole', '%s (userdesc)', + userdesc_parse, objname='user desc') + app.add_js_file('file://moo.js') + app.add_source_suffix('.foo', 'foo') + app.add_source_parser(parsermod.Parser) diff --git a/tests/roots/test-root/extapi.txt b/tests/roots/test-root/extapi.txt new file mode 100644 index 0000000..56be6d8 --- /dev/null +++ b/tests/roots/test-root/extapi.txt @@ -0,0 +1,7 @@ +Extension API tests +=================== + +Testing directives: + +.. clsdir:: + :opt: Bar diff --git a/tests/roots/test-root/extensions.txt b/tests/roots/test-root/extensions.txt new file mode 100644 index 0000000..96b1f8e --- /dev/null +++ b/tests/roots/test-root/extensions.txt @@ -0,0 +1,28 @@ +Test for diverse extensions +=========================== + +extlinks +-------- + +Test diverse links: :issue:`1000` and :pyurl:`dev/`, also with +:issue:`explicit caption <1042>`. + + +todo +---- + +.. todo:: + + Test the todo extension. + +.. todo:: + + Test with |sub| (see #286). + +.. |sub| replace:: substitution references + + +list of all todos +^^^^^^^^^^^^^^^^^ + +.. todolist:: diff --git a/tests/roots/test-root/file_with_special_#_chars.xyz b/tests/roots/test-root/file_with_special_#_chars.xyz new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tests/roots/test-root/file_with_special_#_chars.xyz diff --git a/tests/roots/test-root/footnote.txt b/tests/roots/test-root/footnote.txt new file mode 100644 index 0000000..49cceee --- /dev/null +++ b/tests/roots/test-root/footnote.txt @@ -0,0 +1,60 @@ +:tocdepth: 2 + +Testing footnote and citation +================================ +.. #1058 footnote-backlinks-do-not-work + +numbered footnote +-------------------- + +[1]_ + +auto-numbered footnote +------------------------------ + +[#]_ + +named footnote +-------------------- + +[#foo]_ + +citation +-------------------- + +[bar]_ +[baz_qux]_ + +footnotes in table +-------------------- + +.. list-table:: Table caption [#]_ + :header-rows: 1 + + * - name [#]_ + - description + * - VIDIOC_CROPCAP + - Information about VIDIOC_CROPCAP [#]_ + +footenotes +-------------------- + +.. rubric:: Footnotes + +.. [1] numbered + +.. [#] auto numbered + +.. [#foo] named + +.. rubric:: Citations + +.. [bar] cite + +.. [baz_qux] citation including underscore + +.. [#] footnote in table caption + +.. [#] footnote in table header + +.. [#] footnote in table not in header diff --git a/tests/roots/test-root/images.txt b/tests/roots/test-root/images.txt new file mode 100644 index 0000000..1dc591a --- /dev/null +++ b/tests/roots/test-root/images.txt @@ -0,0 +1,25 @@ +Sphinx image handling +===================== + +.. first, a simple test with direct filename +.. image:: img.png + +.. an image with path name (relative to this directory!) +.. image:: subdir/img.png + :height: 100 + :width: 200 + +.. an image with unspecified extension +.. image:: img.* + +.. a non-local image URI +.. image:: https://www.python.org/static/img/python-logo.png + +.. an image with subdir and unspecified extension +.. image:: subdir/simg.* + +.. an SVG image (for HTML at least) +.. image:: svgimg.* + +.. an image with more than 1 dot in its file name +.. image:: img.foo.png diff --git a/tests/roots/test-root/img.foo.png b/tests/roots/test-root/img.foo.png Binary files differnew file mode 100644 index 0000000..a97e86d --- /dev/null +++ b/tests/roots/test-root/img.foo.png diff --git a/tests/roots/test-root/img.gif b/tests/roots/test-root/img.gif Binary files differnew file mode 100644 index 0000000..8f02686 --- /dev/null +++ b/tests/roots/test-root/img.gif diff --git a/tests/roots/test-root/img.pdf b/tests/roots/test-root/img.pdf Binary files differnew file mode 100644 index 0000000..cacbd85 --- /dev/null +++ b/tests/roots/test-root/img.pdf diff --git a/tests/roots/test-root/img.png b/tests/roots/test-root/img.png Binary files differnew file mode 100644 index 0000000..a97e86d --- /dev/null +++ b/tests/roots/test-root/img.png diff --git a/tests/roots/test-root/includes.txt b/tests/roots/test-root/includes.txt new file mode 100644 index 0000000..19b98ae --- /dev/null +++ b/tests/roots/test-root/includes.txt @@ -0,0 +1,102 @@ +Testing downloadable files +========================== + +Download :download:`img.png` here. +Download :download:`this <subdir/img.png>` there. +Download :download:`file with special characters <file_with_special_#_chars.xyz>`. + +Test file and literal inclusion +=============================== + +.. include:: subdir/include.inc + +.. include:: /subdir/include.inc + +.. literalinclude:: literal.inc + :language: python + +.. should succeed +.. literalinclude:: wrongenc.inc + :encoding: latin-1 + :language: none +.. include:: wrongenc.inc + :encoding: latin-1 + +Literalinclude options +====================== + +.. highlight:: text + +.. cssclass:: inc-pyobj1 +.. literalinclude:: literal.inc + :pyobject: Foo + +.. cssclass:: inc-pyobj2 +.. literalinclude:: literal.inc + :pyobject: Bar.baz + +.. cssclass:: inc-lines +.. literalinclude:: literal.inc + :lines: 6-7,9 + :lineno-start: 6 + +.. cssclass:: inc-startend +.. literalinclude:: literal.inc + :start-after: coding: utf-8 + :end-before: class Foo + +.. cssclass:: inc-preappend +.. literalinclude:: literal.inc + :prepend: START CODE + :append: END CODE + +.. literalinclude:: literal.inc + :start-after: utf-8 + +.. literalinclude:: literal.inc + :end-before: class Foo + +.. literalinclude:: literal.inc + :diff: literal_orig.inc + +.. cssclass:: inc-tab3 +.. literalinclude:: tabs.inc + :tab-width: 3 + :language: text + +.. cssclass:: inc-tab8 +.. literalinclude:: tabs.inc + :tab-width: 8 + :language: python + +.. cssclass:: inc-pyobj-lines-match +.. literalinclude:: literal.inc + :pyobject: Foo + :lineno-match: + +.. cssclass:: inc-lines-match +.. literalinclude:: literal.inc + :lines: 6-7,8 + :lineno-match: + +.. cssclass:: inc-startend-match +.. literalinclude:: literal.inc + :start-after: coding: utf-8 + :end-before: class Foo + :lineno-match: + +Test if dedenting before parsing works. + +.. highlight:: python + +.. cssclass:: inc-pyobj-dedent +.. literalinclude:: literal.inc + :pyobject: Bar.baz + +Docutils include with "literal" +=============================== + +While not recommended, it should work (and leave quotes alone). + +.. include:: quotes.inc + :literal: diff --git a/tests/roots/test-root/index.txt b/tests/roots/test-root/index.txt new file mode 100644 index 0000000..e39c958 --- /dev/null +++ b/tests/roots/test-root/index.txt @@ -0,0 +1,65 @@ +.. Sphinx Tests documentation master file, created by sphinx-quickstart on Wed Jun 4 23:49:58 2008. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Sphinx Tests's documentation! +======================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + :numbered: + :caption: Table of Contents + :name: mastertoc + + extapi + images + subdir/images + subdir/includes + includes + markup + objects + bom + math + autodoc + extensions + footnote + lists + otherext + + http://sphinx-doc.org/ + Latest reference <http://sphinx-doc.org/latest/> + Python <http://python.org/> + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` + +References +========== + +.. [Ref1] Reference target. +.. [Ref_1] Reference target 2. + +Test for issue #1157 +==================== + +This used to crash: + +.. toctree:: + +.. toctree:: + :hidden: + +Test for issue #1700 +==================== + +:ref:`mastertoc` + +Test for indirect hyperlink targets +=================================== + +:ref:`indirect hyperref <other-label>` diff --git a/tests/roots/test-root/lists.txt b/tests/roots/test-root/lists.txt new file mode 100644 index 0000000..0b54454 --- /dev/null +++ b/tests/roots/test-root/lists.txt @@ -0,0 +1,70 @@ +Various kinds of lists +====================== + + +nested enumerated lists +----------------------- + +#. one + +#. two + + #. two.1 + #. two.2 + +#. three + + +enumerated lists with non-default start values +---------------------------------------------- + +0. zero +#. one + +---------------------------------------- + +1. one +#. two + +---------------------------------------- + +2. two +#. three + + +enumerated lists using letters +------------------------------ + +a. a + +b. b + +#. c + +#. d + +---------------------------------------- + +x. x + +y. y + +#. z + +#. { + +definition lists +----------------- + +term1 + description + +term2 (**stronged partially**) + description + +Samp tests +---------- + +:samp:`{variable_only}` +:samp:`{variable} and text` +:samp:`Show {variable} in the middle` diff --git a/tests/roots/test-root/literal.inc b/tests/roots/test-root/literal.inc new file mode 100644 index 0000000..694f15e --- /dev/null +++ b/tests/roots/test-root/literal.inc @@ -0,0 +1,13 @@ +# Literally included file using Python highlighting +# -*- coding: utf-8 -*- + +foo = "Including Unicode characters: üöä" + +class Foo: + pass + +class Bar: + def baz(): + pass + +def bar(): pass diff --git a/tests/roots/test-root/literal_orig.inc b/tests/roots/test-root/literal_orig.inc new file mode 100644 index 0000000..cfb5dd1 --- /dev/null +++ b/tests/roots/test-root/literal_orig.inc @@ -0,0 +1,12 @@ +# Literally included file using Python highlighting + +foo = "Including Unicode characters: üöä" # This will be changed + +class FooOrig: + pass + +class BarOrig: + def baz(): + pass + +def bar(): pass diff --git a/tests/roots/test-root/markup.txt b/tests/roots/test-root/markup.txt new file mode 100644 index 0000000..b59a652 --- /dev/null +++ b/tests/roots/test-root/markup.txt @@ -0,0 +1,455 @@ +:tocdepth: 2 + +.. title:: set by title directive +.. _1024: + +Testing various markup +====================== + +Meta markup +----------- + +.. sectionauthor:: Georg Brandl +.. moduleauthor:: Georg Brandl + +.. contents:: TOC + +.. meta:: + :author: Me + :keywords: docs, sphinx + + +Generic reST +------------ + +A |subst|! + +.. |subst| replace:: global substitution + +.. highlight:: none + +.. _label: + +:: + + some code + +Option list: + +-h help +--help also help + +Line block: + +| line1 +| line2 +| line3 +| line4 +| line5 +| line6 +| line7 + + +Body directives +^^^^^^^^^^^^^^^ + +.. topic:: Title + + Topic body. + +.. sidebar:: Sidebar + :subtitle: Sidebar subtitle + + Sidebar body. + +.. rubric:: Test rubric + +.. epigraph:: Epigraph title + + Epigraph body. + + -- Author + +.. highlights:: Highlights + + Highlights body. + +.. pull-quote:: Pull-quote + + Pull quote body. + +.. compound:: + + a + + b + +.. parsed-literal:: + + with some *markup* inside + + +.. _admonition-section: + +Admonitions +^^^^^^^^^^^ + +.. admonition:: My Admonition + + Admonition text. + +.. note:: + Note text. + +.. warning:: + + Warning text. + +.. _some-label: + +.. tip:: + Tip text. + +Indirect hyperlink targets + +.. _other-label: some-label_ + +Inline markup +------------- + +*Generic inline markup* + +Adding \n to test unescaping. + +* :command:`command\\n` +* :dfn:`dfn\\n` +* :guilabel:`guilabel with &accelerator and \\n` +* :kbd:`kbd\\n` +* :mailheader:`mailheader\\n` +* :makevar:`makevar\\n` +* :manpage:`manpage\\n` +* :mimetype:`mimetype\\n` +* :newsgroup:`newsgroup\\n` +* :program:`program\\n` +* :regexp:`regexp\\n` +* :menuselection:`File --> Close\\n` +* :menuselection:`&File --> &Print` +* :file:`a/{varpart}/b\\n` +* :samp:`print {i}\\n` + +*Linking inline markup* + +* :pep:`8` +* :pep:`Python Enhancement Proposal #8 <8>` +* :rfc:`1` +* :rfc:`Request for Comments #1 <1>` +* :envvar:`HOME` +* :keyword:`with` +* :token:`try statement <try_stmt>` +* :ref:`admonition-section` +* :ref:`here <some-label>` +* :ref:`there <other-label>` +* :ref:`my-figure` +* :ref:`my-figure-name` +* :ref:`my-table` +* :ref:`my-table-name` +* :ref:`my-code-block` +* :ref:`my-code-block-name` +* :ref:`1024` +* :numref:`my-figure` +* :numref:`my-figure-name` +* :numref:`my-table` +* :numref:`my-table-name` +* :numref:`my-code-block` +* :numref:`my-code-block-name` +* :doc:`subdir/includes` +* ``:download:`` is tested in includes.txt +* :option:`Python -c option <python -c>` + +Test :abbr:`abbr (abbreviation)` and another :abbr:`abbr (abbreviation)`. + +Testing the :index:`index` role, also available with +:index:`explicit <pair: title; explicit>` title. + +.. _with: + +With +---- + +(Empty section.) + + +Tables +------ + +.. tabularcolumns:: |L|p{5cm}|R| + +.. _my-table: + +.. table:: my table + :name: my-table-name + + +----+----------------+----+ + | 1 | * Block elems | x | + | | * In table | | + +----+----------------+----+ + | 2 | Empty cells: | | + +----+----------------+----+ + +.. table:: empty cell in table header + + ===== ====== + \ + ===== ====== + 1 2 + 3 4 + ===== ====== + +Tables with multirow and multicol: + +.. only:: latex + + +----+----------------+---------+ + | 1 | test! | c | + +----+---------+------+ | + | 2 | col | col | | + | y +---------+------+----+----+ + | x | multi-column cell | x | + +----+---------------------+----+ + + +----+ + | 1 | + + + + | | + +----+ + +.. list-table:: + :header-rows: 0 + + * - .. figure:: img.png + + figure in table + + +Figures +------- + +.. _my-figure: + +.. figure:: img.png + :name: my-figure-name + + My caption of the figure + + My description paragraph of the figure. + + Description paragraph is wrapped with legend node. + +.. figure:: rimg.png + :align: right + + figure with align option + +.. figure:: rimg.png + :align: right + :figwidth: 50% + + figure with align & figwidth option + +.. figure:: rimg.png + :align: right + :width: 3cm + + figure with align & width option + +Version markup +-------------- + +.. versionadded:: 0.6 + Some funny **stuff**. + +.. versionchanged:: 0.6 + Even more funny stuff. + +.. deprecated:: 0.6 + Boring stuff. + +.. versionadded:: 1.2 + + First paragraph of versionadded. + +.. versionchanged:: 1.2 + First paragraph of versionchanged. + + Second paragraph of versionchanged. + + +Code blocks +----------- + +.. _my-code-block: + +.. code-block:: ruby + :linenos: + :caption: my ruby code + :name: my-code-block-name + + def ruby? + false + end + +Misc stuff +---------- + +Stuff [#]_ + +Reference lookup: [Ref1]_ (defined in another file). +Reference lookup underscore: [Ref_1]_ + +.. seealso:: something, something else, something more + + `Google <http://www.google.com>`_ + For everything. + +.. hlist:: + :columns: 4 + + * This + * is + * a horizontal + * list + * with several + * items + +.. rubric:: Side note + +This is a side note. + +This tests :CLASS:`role names in uppercase`. + +.. centered:: LICENSE AGREEMENT + +.. acks:: + + * Terry Pratchett + * J. R. R. Tolkien + * Monty Python + +.. glossary:: + :sorted: + + boson + Particle with integer spin. + + *fermion* + Particle with half-integer spin. + + tauon + myon + electron + Examples for fermions. + + über + Gewisse + + ähnlich + Dinge + +.. productionlist:: + try_stmt: `try1_stmt` | `try2_stmt` + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` + + +Index markup +------------ + +.. index:: + single: entry + pair: entry; pair + double: entry; double + triple: index; entry; triple + see: from; to + seealso: fromalso; toalso + +.. index:: + !Main, !Other + !single: entry; pair + +:index:`!Main` + +.. _ölabel: + +Ö... Some strange characters +---------------------------- + +Testing öäü... + + +Only directive +-------------- + +.. only:: html + + In HTML. + +.. only:: latex + + In LaTeX. + +.. only:: html or latex + + In both. + +.. only:: confpytag and (testtag or nonexisting_tag) + + Always present, because set through conf.py/command line. + + +Any role +-------- + +.. default-role:: any + +Test referencing to `headings <with>` and `objects <func_without_body>`. +Also `modules <mod>` and `classes <Time>`. + +More domains: + +* `JS <bar.baz>` +* `C <SphinxType>` +* `myobj` (user markup) +* `n::Array` +* `perl -c` + +.. default-role:: + + +Smart quotes +------------ + +* Smart "quotes" in English 'text'. +* Smart --- long and -- short dashes. +* Ellipsis... +* No smartypants in literal blocks: ``foo--"bar"...``. + +.. only:: html + + .. LaTeX does not like Cyrillic letters in this test, so it is HTML only. + + .. rst-class:: language-ru + + Этот "абзац" должен использовать 'русские' кавычки. + + .. rst-class:: language-fr + + Il dit : "C'est 'super' !" + +.. rubric:: Footnotes + +.. [#] Like footnotes. + diff --git a/tests/roots/test-root/math.txt b/tests/roots/test-root/math.txt new file mode 100644 index 0000000..5a209be --- /dev/null +++ b/tests/roots/test-root/math.txt @@ -0,0 +1,31 @@ +Test math extensions :math:`E = m c^2` +====================================== + +This is inline math: :math:`a^2 + b^2 = c^2`. + +.. math:: a^2 + b^2 = c^2 + +.. math:: + + a + 1 < b + +.. math:: + :label: foo + + e^{i\pi} = 1 + +.. math:: + :label: + + e^{ix} = \cos x + i\sin x + +.. math:: + + n \in \mathbb N + +.. math:: + :nowrap: + + a + 1 < b + +Referencing equation :eq:`foo`. diff --git a/tests/roots/test-root/objects.txt b/tests/roots/test-root/objects.txt new file mode 100644 index 0000000..ed5f2c2 --- /dev/null +++ b/tests/roots/test-root/objects.txt @@ -0,0 +1,262 @@ +Testing object descriptions +=========================== + +.. function:: func_without_module(a, b, *c[, d]) + + Does something. + +.. function:: func_without_body() + +.. function:: func_with_unknown_field() + + : : + + : empty field name: + + :field_name: + + :field_name all lower: + + :FIELD_NAME: + + :FIELD_NAME ALL CAPS: + + :Field_Name: + + :Field_Name All Word Caps: + + :Field_name: + + :Field_name First word cap: + + :FIELd_name: + + :FIELd_name PARTial caps: + +.. function:: func_noindex + :no-index: + +.. function:: func_with_module + :module: foolib + +Referring to :func:`func with no index <func_noindex>`. +Referring to :func:`nothing <>`. + +.. module:: mod + :synopsis: Module synopsis. + :platform: UNIX + +.. function:: func_in_module + +.. class:: Cls + + .. method:: meth1 + + .. staticmethod:: meths + + .. attribute:: attr + +.. explicit class given +.. method:: Cls.meth2 + +.. explicit module given +.. exception:: Error(arg1, arg2) + :module: errmod + +.. data:: var + + +.. currentmodule:: None + +.. function:: func_without_module2() -> annotation + +.. object:: long(parameter, \ + list) + another one + +.. class:: TimeInt + + Has only one parameter (triggers special behavior...) + + :param moo: |test| + :type moo: |test| + +.. |test| replace:: Moo + +.. class:: Time(hour, minute, isdst) + + :param year: The year. + :type year: TimeInt + :param TimeInt minute: The minute. + :param isdst: whether it's DST + :type isdst: * some complex + * expression + :returns: a new :class:`Time` instance + :rtype: Time + :raises Error: if the values are out of range + :ivar int hour: like *hour* + :ivar minute: like *minute* + :vartype minute: int + :param hour: Some parameter + :type hour: DuplicateType + :param hour: Duplicate param. Should not lead to crashes. + :type hour: DuplicateType + :param .Cls extcls: A class from another module. + +.. raw:: latex + + \begingroup + \let\oldhref\href + \def\href{\ifnum\catcode`\-=\active\errorwithsphinxhref\fi\oldhref} + +.. class:: MyClass + + .. attribute:: config + :type: sphinx.config.Config + + A configuration object. + +.. raw:: latex + + \endgroup + +C items +======= + +.. c:function:: void Sphinx_DoSomething() + +.. c:member:: int SphinxStruct.member + +.. c:macro:: SPHINX_USE_PYTHON + +.. c:type:: SphinxType + +.. c:var:: int sphinx_global + +.. c:function:: PyObject* Py_SphinxFoo(void) + + +Javascript items +================ + +.. js:function:: foo() + +.. js:data:: bar + +.. documenting the method of any object +.. js:function:: bar.baz(href, callback[, errback]) + + :param string href: The location of the resource. + :param callback: Gets called with the data returned by the resource. + :throws InvalidHref: If the `href` is invalid. + :returns: `undefined` + +.. js:attribute:: bar.spam + +References +========== + +Referencing :class:`mod.Cls` or :Class:`mod.Cls` should be the same. + +With target: :c:func:`Sphinx_DoSomething()` (parentheses are handled), +:c:member:`SphinxStruct.member`, :c:macro:`SPHINX_USE_PYTHON`, +:c:type:`SphinxType *` (pointer is handled), :c:data:`sphinx_global`. + +Without target: :c:func:`CFunction`. :c:func:`!malloc`. + +:js:func:`foo()` +:js:func:`foo` + +:js:data:`bar` +:js:func:`bar.baz()` +:js:func:`bar.baz` +:js:func:`~bar.baz()` + +:js:attr:`bar.baz` + + +Others +====== + +.. envvar:: HOME + +.. program:: python + +.. cmdoption:: -c command + +.. program:: perl + +.. cmdoption:: -c + +.. option:: +p + +.. option:: --ObjC++ + +.. option:: --plugin.option + +.. option:: create-auth-token + +.. option:: arg + +.. option:: -j[=N] + +Link to :option:`perl +p`, :option:`--ObjC++`, :option:`--plugin.option`, :option:`create-auth-token`, :option:`arg` and :option:`-j` + +.. program:: hg + +.. option:: commit + +.. program:: git commit + +.. option:: -p + +Link to :option:`hg commit` and :option:`git commit -p`. + +.. option:: --abi={TYPE} + +.. option:: --test={WHERE}-{COUNT} + +.. option:: --wrap=\{\{value\}\} + +.. option:: -allowable_client {client_name} + +Foo bar. + +Test repeated option directive. + +.. option:: -mapi + + My API. + +.. option:: -mapi=secret + + My secret API. + +Reference the first option :option:`-mapi=secret`, :option:`-mapi[=xxx]` +or :option:`-mapi with_space`. + + +User markup +=========== + +.. userdesc:: myobj:parameter + + Description of userdesc. + + +Referencing :userdescrole:`myobj`. + + +CPP domain +========== + +.. cpp:class:: n::Array + + .. cpp:function:: T& operator[]( unsigned j ) + const T& operator[]( unsigned j ) const + +.. cpp:function:: template<typename T1, typename T2> \ + requires A<T1, T2> \ + void f() + +- :cpp:expr:`a + b` diff --git a/tests/roots/test-root/otherext.foo b/tests/roots/test-root/otherext.foo new file mode 100644 index 0000000..531ea29 --- /dev/null +++ b/tests/roots/test-root/otherext.foo @@ -0,0 +1,2 @@ +The contents of this file are ignored. +The file is "parsed" using Parser in the tests/root/parsermod.py file. diff --git a/tests/roots/test-root/parsermod.py b/tests/roots/test-root/parsermod.py new file mode 100644 index 0000000..de0849c --- /dev/null +++ b/tests/roots/test-root/parsermod.py @@ -0,0 +1,14 @@ +from docutils import nodes +from docutils.parsers import Parser + + +class Parser(Parser): + supported = ('foo',) + + def parse(self, input, document): + section = nodes.section(ids=['id1']) + section += nodes.title('Generated section', 'Generated section') + document += section + + def get_transforms(self): + return [] diff --git a/tests/roots/test-root/quotes.inc b/tests/roots/test-root/quotes.inc new file mode 100644 index 0000000..276cc56 --- /dev/null +++ b/tests/roots/test-root/quotes.inc @@ -0,0 +1 @@ +Testing "quotes" in literal 'included' text. diff --git a/tests/roots/test-root/rimg.png b/tests/roots/test-root/rimg.png Binary files differnew file mode 100644 index 0000000..fda6cd2 --- /dev/null +++ b/tests/roots/test-root/rimg.png diff --git a/tests/roots/test-root/special/api.h b/tests/roots/test-root/special/api.h new file mode 100644 index 0000000..2bf2382 --- /dev/null +++ b/tests/roots/test-root/special/api.h @@ -0,0 +1,2 @@ +PyAPI_FUNC(PyObject *) Py_SphinxTest(void); +PyAPI_FUNC(PyObject *) Py_SphinxFoo(void); diff --git a/tests/roots/test-root/special/code.py b/tests/roots/test-root/special/code.py new file mode 100644 index 0000000..b7934b2 --- /dev/null +++ b/tests/roots/test-root/special/code.py @@ -0,0 +1,2 @@ +print("line 1") +print("line 2") diff --git a/tests/roots/test-root/subdir/excluded.txt b/tests/roots/test-root/subdir/excluded.txt new file mode 100644 index 0000000..5df3139 --- /dev/null +++ b/tests/roots/test-root/subdir/excluded.txt @@ -0,0 +1,2 @@ +Excluded file -- should *not* be read as source +----------------------------------------------- diff --git a/tests/roots/test-root/subdir/images.txt b/tests/roots/test-root/subdir/images.txt new file mode 100644 index 0000000..f2adf88 --- /dev/null +++ b/tests/roots/test-root/subdir/images.txt @@ -0,0 +1,6 @@ +Image including source in subdir +================================ + +.. image:: img.* + +.. image:: /rimg.png diff --git a/tests/roots/test-root/subdir/img.png b/tests/roots/test-root/subdir/img.png Binary files differnew file mode 100644 index 0000000..a97e86d --- /dev/null +++ b/tests/roots/test-root/subdir/img.png diff --git a/tests/roots/test-root/subdir/include.inc b/tests/roots/test-root/subdir/include.inc new file mode 100644 index 0000000..d89275d --- /dev/null +++ b/tests/roots/test-root/subdir/include.inc @@ -0,0 +1,5 @@ +.. This file is included by contents.txt. + +.. Paths in included files are relative to the file that + includes them +.. image:: subdir/img.png diff --git a/tests/roots/test-root/subdir/includes.txt b/tests/roots/test-root/subdir/includes.txt new file mode 100644 index 0000000..627dcfb --- /dev/null +++ b/tests/roots/test-root/subdir/includes.txt @@ -0,0 +1,18 @@ +Including in subdir +=================== + +.. absolute filename +.. literalinclude:: /special/code.py + :lines: 1 + +.. relative filename +.. literalinclude:: ../special/code.py + :lines: 2 + +Absolute :download:`/img.png` download. + +.. absolute image filename +.. image:: /img.png + +.. absolute include filename +.. include:: /test.inc diff --git a/tests/roots/test-root/subdir/simg.png b/tests/roots/test-root/subdir/simg.png Binary files differnew file mode 100644 index 0000000..a97e86d --- /dev/null +++ b/tests/roots/test-root/subdir/simg.png diff --git a/tests/roots/test-root/svgimg.pdf b/tests/roots/test-root/svgimg.pdf Binary files differnew file mode 100644 index 0000000..cacbd85 --- /dev/null +++ b/tests/roots/test-root/svgimg.pdf diff --git a/tests/roots/test-root/svgimg.svg b/tests/roots/test-root/svgimg.svg new file mode 100644 index 0000000..2bae0b9 --- /dev/null +++ b/tests/roots/test-root/svgimg.svg @@ -0,0 +1,4 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" height="60" width="60"> + <circle cx="40" cy="40" r="24" style="stroke:#000000; fill:#ffffff"/> +</svg> diff --git a/tests/roots/test-root/tabs.inc b/tests/roots/test-root/tabs.inc new file mode 100644 index 0000000..20b5182 --- /dev/null +++ b/tests/roots/test-root/tabs.inc @@ -0,0 +1,5 @@ +Tabs include file test +---------------------- + +The next line has a tab: +-| |- diff --git a/tests/roots/test-root/test.inc b/tests/roots/test-root/test.inc new file mode 100644 index 0000000..4773390 --- /dev/null +++ b/tests/roots/test-root/test.inc @@ -0,0 +1,3 @@ +.. This file is included from subdir/includes.txt. + +This is an include file. diff --git a/tests/roots/test-root/wrongenc.inc b/tests/roots/test-root/wrongenc.inc new file mode 100644 index 0000000..700f613 --- /dev/null +++ b/tests/roots/test-root/wrongenc.inc @@ -0,0 +1,3 @@ +This file is encoded in latin-1 but at first read as utf-8. + +Max Strau a in Mnchen eine Leberkssemmel. |
