From 6637322c8ab1c5ff80a2b6ca59c9ba1d40aeba2c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 19:56:50 +0200 Subject: Adding upstream version 2.0.0+dfsg. Signed-off-by: Daniel Baumann --- docs/demo/api.rst | 152 +++++++ docs/demo/demo.rst | 477 +++++++++++++++++++++ docs/demo/level1/index.rst | 9 + docs/demo/level1/level2/index.rst | 9 + docs/demo/level1/level2/level3/index.rst | 9 + docs/demo/level1/level2/level3/level4/index.rst | 9 + .../level1/level2/level3/level4/level5/index.rst | 9 + .../level2/level3/level4/level5/level6/index.rst | 4 + docs/demo/lists_tables.rst | 371 ++++++++++++++++ docs/demo/long.rst | 214 +++++++++ docs/demo/static/favicon.ico | Bin 0 -> 766 bytes docs/demo/static/logo-wordmark-light.svg | 134 ++++++ docs/demo/static/screen_desktop.png | Bin 0 -> 140497 bytes docs/demo/static/screen_mobile.png | Bin 0 -> 85705 bytes docs/demo/static/yi_jing_01_chien.jpg | Bin 0 -> 6614 bytes docs/demo/structure.rst | 101 +++++ docs/demo/test_py_module/__init__.py | 0 docs/demo/test_py_module/test.py | 148 +++++++ 18 files changed, 1646 insertions(+) create mode 100644 docs/demo/api.rst create mode 100644 docs/demo/demo.rst create mode 100644 docs/demo/level1/index.rst create mode 100644 docs/demo/level1/level2/index.rst create mode 100644 docs/demo/level1/level2/level3/index.rst create mode 100644 docs/demo/level1/level2/level3/level4/index.rst create mode 100644 docs/demo/level1/level2/level3/level4/level5/index.rst create mode 100644 docs/demo/level1/level2/level3/level4/level5/level6/index.rst create mode 100644 docs/demo/lists_tables.rst create mode 100644 docs/demo/long.rst create mode 100644 docs/demo/static/favicon.ico create mode 100644 docs/demo/static/logo-wordmark-light.svg create mode 100644 docs/demo/static/screen_desktop.png create mode 100644 docs/demo/static/screen_mobile.png create mode 100644 docs/demo/static/yi_jing_01_chien.jpg create mode 100644 docs/demo/structure.rst create mode 100644 docs/demo/test_py_module/__init__.py create mode 100644 docs/demo/test_py_module/test.py (limited to 'docs/demo') diff --git a/docs/demo/api.rst b/docs/demo/api.rst new file mode 100644 index 0000000..6c3163d --- /dev/null +++ b/docs/demo/api.rst @@ -0,0 +1,152 @@ +*************************************** +API documentation and generated content +*************************************** + +.. contents:: Table of Contents + +:mod:`test_py_module` +===================== + +.. automodule:: test_py_module.test + :members: + :private-members: + :special-members: + + +C++ API +======= + +.. cpp:type:: MyType + + Some type + +.. cpp:function:: const MyType Foo(const MyType bar) + + Some function type thing + +.. cpp:class:: template std::array + + Some cpp class + +.. cpp:member:: float Sphinx::version + + The description of Sphinx::version. + +.. cpp:var:: int version + + The description of version. + +.. cpp:type:: std::vector List + + The description of List type. + +.. cpp:enum:: MyEnum + + An unscoped enum. + + .. cpp:enumerator:: A + +.. cpp:enum-class:: MyScopedEnum + + A scoped enum. + + .. cpp:enumerator:: B + +.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type::type + + A scoped enum with non-default visibility, and with a specified underlying type. + + .. cpp:enumerator:: B + + +JavaScript API +============== + +.. Copied from sphinx-doc/sphinx/tests/roots + +.. js:module:: module_a.submodule + +* Link to :js:class:`ModTopLevel` + +.. js:class:: ModTopLevel + + * Link to :js:meth:`mod_child_1` + * Link to :js:meth:`ModTopLevel.mod_child_1` + +.. js:method:: ModTopLevel.mod_child_1 + + * Link to :js:meth:`mod_child_2` + +.. js:method:: ModTopLevel.mod_child_2 + + * Link to :js:meth:`module_a.submodule.ModTopLevel.mod_child_1` + +.. js:module:: module_b.submodule + +* Link to :js:class:`ModTopLevel` + +.. js:class:: ModNested + + .. js:method:: nested_child_1 + + * Link to :js:meth:`nested_child_2` + + .. js:method:: nested_child_2 + + * Link to :js:meth:`nested_child_1` + + +Generated Index +=============== + +Part of the sphinx build process is to generate an index file: :ref:`genindex`. + + +Optional parameter args +======================= + +At this point optional parameters `cannot be generated from code`_. +However, some projects will manually do it, like so: + +This example comes from `django-payments module docs`_. + +.. class:: payments.dotpay.DotpayProvider(seller_id, pin[, channel=0[, lock=False], lang='pl']) + + This backend implements payments using a popular Polish gateway, `Dotpay.pl `_. + + Due to API limitations there is no support for transferring purchased items. + + + :param seller_id: Seller ID assigned by Dotpay + :param pin: PIN assigned by Dotpay + :param channel: Default payment channel (consult reference guide) + :param lang: UI language + :param lock: Whether to disable channels other than the default selected above + +.. _cannot be generated from code: https://groups.google.com/forum/#!topic/sphinx-users/_qfsVT5Vxpw +.. _django-payments module docs: http://django-payments.readthedocs.org/en/latest/modules.html#payments.authorizenet.AuthorizeNetProvide + + +Data +==== + +.. data:: Data_item_1 + Data_item_2 + Data_item_3 + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce congue elit eu hendrerit mattis. + +Some data link :data:`Data_item_1`. + + +Sphinx Extensions +================= + +sphinx.ext.autosummary +---------------------- + +.. autosummary:: + + test_py_module.test.add_numbers + test_py_module.test.subtract_numbers + test_py_module.test.Foo diff --git a/docs/demo/demo.rst b/docs/demo/demo.rst new file mode 100644 index 0000000..e9f470d --- /dev/null +++ b/docs/demo/demo.rst @@ -0,0 +1,477 @@ +.. This is a comment. Note how any initial comments are moved by + transforms to after the document title, subtitle, and docinfo. + +.. demo.rst from: http://docutils.sourceforge.net/docs/user/rst/demo.txt + +.. |EXAMPLE| image:: static/yi_jing_01_chien.jpg + :width: 1em + +********************** +Paragraph Level Markup +********************** + +.. contents:: Table of Contents + +Inline Markup +============= + +Paragraphs contain text and may contain inline markup: *emphasis*, **strong emphasis**, ``inline literals``, +standalone hyperlinks (http://www.python.org), external hyperlinks (Python_), internal cross-references (example_), +external hyperlinks with embedded URIs (`Python web site `__), footnote references +(manually numbered [1]_, anonymous auto-numbered [#]_, labeled auto-numbered [#label]_, or symbolic [*]_), +citation references ([12]_), substitution references (|example|), and _`inline hyperlink targets` +(see Targets_ below for a reference back to here). Character-level inline markup is also possible +(although exceedingly ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by |problematic| +text (generated by processing errors; this one is intentional). + +Also with ``sphinx.ext.autodoc``, which I use in the demo, I can link to :class:`test_py_module.test.Foo`. +It will link you right to my code documentation for it. + +The default role for [1]_ interpreted text is `Title Reference`. Here are some explicit interpreted text roles: +a PEP reference (:PEP:`287`); an RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`; +and explicit roles for :emphasis:`standard` :strong:`inline` :literal:`markup`. + +GUI labels are a useful way to indicate that :guilabel:`Some action` is to be taken by the user. +The GUI label should not run over ``line-height`` so as not to :guilabel:`interfere` with text from adjacent lines. + +Key-bindings indicate that [1]_ the read is to press a button on the keyboard or mouse, +for example :kbd:`MMB` and :kbd:`Shift-MMB`. Another useful markup to indicate a user action +is to use ``menuselection`` this [1]_ can [1]_ be [1]_ used [1]_ to [1]_ show [1]_ short [1]_ and long menus in software. +For example, and ``menuselection`` can be seen here that breaks is too long to fit on this line. +:menuselection:`My --> Software --> Some menu --> Some sub menu 1 --> sub menu 2`. + +.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! + +Let's test wrapping and whitespace significance in inline literals: +``This is an example of --inline-literal --text, --including some-- +strangely--hyphenated-words. Adjust-the-width-of-your-browser-window +to see how the text is wrapped. -- ---- -------- Now note the +spacing between the words of this sentence (words +should be grouped in pairs).`` + +If the ``--pep-references`` option was supplied, there should be a live link to PEP 258 here. + +.. regression test for https://github.com/readthedocs/sphinx_rtd_theme/pull/1193 + +Very long URLs should be wrapped so lines do not overflow and cause horizontal scrolling: https://www.google.com/search?hl=en&q=very%20long%20url%20example%20of%20a%20url%20that%20is%20extremely%20long%20you%20probably%20want%20to%20avoid%20it%20but%20here%20we%20are + +Math +==== + +This is a test. Here is an equation: +:math:`X_{0:5} = (X_0, X_1, X_2, X_3, X_4)`. +Here is another: + +.. math:: + :label: This is a label + + \nabla^2 f = + \frac{1}{r^2} \frac{\partial}{\partial r} + \left( r^2 \frac{\partial f}{\partial r} \right) + + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} + \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2} + +You can add a link to equations like the one above :eq:`This is a label` by using ``:eq:``. + +Meta +==== + +.. meta:: + :keywords: reStructuredText, demonstration, demo, parser + :description lang=en: A demonstration of the reStructuredText + markup language, containing examples of all basic + constructs and many advanced constructs. + +Blocks +====== + +Literal Blocks +-------------- + +Literal blocks are indicated with a double-colon ("::") at the end of +the preceding paragraph (over there ``-->``). They can be indented:: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + +Or they can be quoted without indentation:: + +>> Great idea! +> +> Why didn't I think of that? + +Line Blocks +----------- + +| This is a line block. It ends with a blank line. +| Each new line begins with a vertical bar ("|"). +| Line breaks and initial indents are preserved. +| Continuation lines are wrapped portions of long lines; + they begin with a space in place of the vertical bar. +| The left edge of a continuation line need not be aligned with + the left edge of the text above it. + +| This is a second line block. +| +| Blank lines are permitted internally, but they must begin with a "|". + +Take it away, Eric the Orchestra Leader! + + | A one, two, a one two three four + | + | Half a bee, philosophically, + | must, *ipso facto*, half not be. + | But half the bee has got to be, + | *vis a vis* its entity. D'you see? + | + | But can a bee be said to be + | or not to be an entire bee, + | when half the bee is not a bee, + | due to some ancient injury? + | + | Singing... + +Block Quotes +------------ + +Block quotes consist of indented body elements: + + My theory by A. Elk. Brackets Miss, brackets. This theory goes + as follows and begins now. All brontosauruses are thin at one + end, much much thicker in the middle and then thin again at the + far end. That is my theory, it is mine, and belongs to me and I + own it, and what it is too. + + -- Anne Elk (Miss) + +Doctest Blocks +-------------- + +>>> print 'Python-specific usage examples; begun with ">>>"' +Python-specific usage examples; begun with ">>>" +>>> print '(cut and pasted from interactive Python sessions)' +(cut and pasted from interactive Python sessions) + +Code Blocks +----------- + +.. parsed-literal:: + + # parsed-literal test + curl -O http://someurl/release-|version|.tar-gz + + +.. code-block:: json + :caption: Code Blocks can have captions. + + { + "windows": [ + { + "panes": [ + { + "shell_command": [ + "echo 'did you know'", + "echo 'you can inline'" + ] + }, + { + "shell_command": "echo 'single commands'" + }, + "echo 'for panes'" + ], + "window_name": "long form" + } + ], + "session_name": "shorthands" + } + +Emphasized lines with line numbers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + :linenos: + :emphasize-lines: 3,5 + + def some_function(): + interesting = False + print 'This line is highlighted.' + print 'This one is not...' + print '...but this one is.' + +Sidebar +======= + +.. sidebar:: Ch'ien / The Creative + + .. image:: static/yi_jing_01_chien.jpg + + *Above* CH'IEN THE CREATIVE, HEAVEN + + *Below* CH'IEN THE CREATIVE, HEAVEN + +The first hexagram is made up of six unbroken lines. These unbroken lines stand for the primal power, +which is light-giving, active, strong, and of the spirit. The hexagram is consistently strong in character, +and since it is without weakness, its essence is power or energy. Its image is heaven. +Its energy is represented as unrestricted by any fixed conditions in space and is therefore conceived of as motion. +Time is regarded as the basis of this motion. +Thus the hexagram includes also the power of time and the power of persisting in time, that is, duration. + +The power represented by the hexagram is to be interpreted in a dual sense in terms of its action +on the universe and of its action on the world of men. In relation to the universe, the hexagram expresses the strong, +creative action of the Deity. In relation to the human world, it denotes the creative action of the holy man or sage, +of the ruler or leader of men, who through his power awakens and develops their higher nature. + +Code with Sidebar +----------------- + +.. sidebar:: A code example + + With a sidebar on the right. + +.. literalinclude:: test_py_module/test.py + :language: python + :caption: Literal includes can also have captions. + :linenos: + :lines: 1-40 + +References +========== + +Footnotes +--------- + +.. [1] A footnote contains body elements, consistently indented by at + least 3 spaces. + + This is the footnote's second paragraph. + +.. [#label] Footnotes may be numbered, either manually (as in [1]_) or + automatically using a "#"-prefixed label. This footnote has a + label so it can be referred to from multiple places, both as a + footnote reference ([#label]_) and as a hyperlink reference + (label_). + +.. [#] This footnote is numbered automatically and anonymously using a + label of "#" only. + +.. [*] Footnotes may also use symbols, specified with a "*" label. + Here's a reference to the next footnote: [*]_. + +.. [*] This footnote shows the next symbol in the sequence. + +.. [4] Here's an unreferenced footnote, with a reference to a + nonexistent footnote: [5]_. + +Citations +--------- + +.. [Citation] This is the citation I made, let's make this extremely long so that we can tell that it doesn't follow the normal responsive table stuff. + +.. [12] This citation has some ``code blocks`` in it, maybe some **bold** and + *italics* too. Heck, lets put a link to a meta citation [13]_ too. + +.. [13] This citation will have two backlinks. + + +Here's a reference to the above, [Citation]_, and a [nonexistent]_ citation. + +Glossary +-------- + +This is a glossary with definition terms for thing like :term:`Writing`: + +.. glossary:: + + Documentation + Provides users with the knowledge they need to use something. + + Reading + The process of taking information into ones mind through the use of eyes. + + Writing + The process of putting thoughts into a medium for other people to :term:`read `. + +Targets +------- + +.. _example: + +This paragraph is pointed to by the explicit "example" target. +A reference can be found under `Inline Markup`_, above. `Inline +hyperlink targets`_ are also possible. + +Section headers are implicit targets, referred to by name. See +Targets_, which is a subsection of `References`_. + +Explicit external targets are interpolated into references such as "Python_". + +.. _Python: http://www.python.org/ + +Targets may be indirect and anonymous. Thus `this phrase`__ may also +refer to the Targets_ section. + +__ Targets_ + +Here's a `hyperlink reference without a target`_, which generates an error. + + +Directives +========== + +Contents +-------- + +.. contents:: :local: + +These are just a sample of the many reStructuredText Directives. For others, please see: +http://docutils.sourceforge.net/docs/ref/rst/directives.html. + + +Centered text +------------- + +You can create a statement with centered text with ``.. centered::`` + +.. centered:: This is centered text! + +Images & Figures +---------------- + +Images +^^^^^^ + +An image directive (also clickable -- a hyperlink reference): + +.. image:: static/yi_jing_01_chien.jpg + :target: directives_ + +Figures +^^^^^^^ + +.. figure:: static/yi_jing_01_chien.jpg + :alt: reStructuredText, the markup syntax + + A figure is an image with a caption and/or a legend: + + +------------+-----------------------------------------------+ + | re | Revised, revisited, based on 're' module. | + +------------+-----------------------------------------------+ + | Structured | Structure-enhanced text, structuredtext. | + +------------+-----------------------------------------------+ + | Text | Well it is, isn't it? | + +------------+-----------------------------------------------+ + + This paragraph is also part of the legend. + +A figure directive with center alignment + +.. figure:: static/yi_jing_01_chien.jpg + :align: center + + This caption should be centered. + +Admonitions +----------- + +.. Attention:: Directives at large. + +.. Caution:: Don't take any wooden nickels. + +.. DANGER:: Mad scientist at work! + +.. Error:: Does not compute. + +.. Hint:: It's bigger than a bread box. + +.. Important:: + - Wash behind your ears. + - Clean up your room. + + - Including the closet. + - The bathroom too. + + - Take the trash out of the bathroom. + - Clean the sink. + - Call your mother. + - Back up your data. + +.. Note:: This is a note. + Equations within a note: + :math:`G_{\mu\nu} = 8 \pi G (T_{\mu\nu} + \rho_\Lambda g_{\mu\nu})`. + +.. Tip:: 15% if the service is good. + + +---------+ + | Example | + +=========+ + | Thing1 | + +---------+ + | Thing2 | + +---------+ + | Thing3 | + +---------+ + +.. WARNING:: Strong prose may provoke extreme mental exertion. + Reader discretion is strongly advised. + +.. admonition:: And, by the way... + + You can make up your own admonition too. + +Topics, Sidebars, and Rubrics +----------------------------- + +.. sidebar:: Sidebar Title + :subtitle: Optional Subtitle + + This is a sidebar. It is for text outside the flow of the main + text. + + .. rubric:: This is a rubric inside a sidebar + + Sidebars often appears beside the main text with a border and + background color. + +.. topic:: Topic Title + + This is a topic. + +.. rubric:: This is a rubric + +Target Footnotes +---------------- + +.. target-notes:: + +Replacement Text +---------------- + +I recommend you try |Python|_. + +.. |Python| replace:: Python, *the* best language around + +Compound Paragraph +------------------ + +.. compound:: + + This paragraph contains a literal block:: + + Connecting... OK + Transmitting data... OK + Disconnecting... OK + + and thus consists of a simple paragraph, a literal block, and + another simple paragraph. Nonetheless it is semantically *one* + paragraph. + +This construct is called a *compound paragraph* and can be produced +with the "compound" directive. + +Download Links +============== + +:download:`This long long long long long long long long long long long long long long long download link should be blue, normal weight text with a leading icon, and should wrap white-spaces ` diff --git a/docs/demo/level1/index.rst b/docs/demo/level1/index.rst new file mode 100644 index 0000000..e210638 --- /dev/null +++ b/docs/demo/level1/index.rst @@ -0,0 +1,9 @@ + +****************** +Breadcrumb Level 1 +****************** + + .. toctree:: + :maxdepth: 3 + + level2/index.rst diff --git a/docs/demo/level1/level2/index.rst b/docs/demo/level1/level2/index.rst new file mode 100644 index 0000000..26931c7 --- /dev/null +++ b/docs/demo/level1/level2/index.rst @@ -0,0 +1,9 @@ + +****************************************** +:mod:`Breadcrumb Level 2 ` +****************************************** + + .. toctree:: + :maxdepth: 3 + + level3/index.rst diff --git a/docs/demo/level1/level2/level3/index.rst b/docs/demo/level1/level2/level3/index.rst new file mode 100644 index 0000000..bc3c195 --- /dev/null +++ b/docs/demo/level1/level2/level3/index.rst @@ -0,0 +1,9 @@ + +****************** +Breadcrumb Level 3 +****************** + + .. toctree:: + :maxdepth: 3 + + level4/index.rst diff --git a/docs/demo/level1/level2/level3/level4/index.rst b/docs/demo/level1/level2/level3/level4/index.rst new file mode 100644 index 0000000..9a8c0fa --- /dev/null +++ b/docs/demo/level1/level2/level3/level4/index.rst @@ -0,0 +1,9 @@ + +****************** +Breadcrumb Level 4 +****************** + + .. toctree:: + :maxdepth: 3 + + level5/index.rst diff --git a/docs/demo/level1/level2/level3/level4/level5/index.rst b/docs/demo/level1/level2/level3/level4/level5/index.rst new file mode 100644 index 0000000..ca590c9 --- /dev/null +++ b/docs/demo/level1/level2/level3/level4/level5/index.rst @@ -0,0 +1,9 @@ + +****************** +Breadcrumb Level 5 +****************** + + .. toctree:: + :maxdepth: 3 + + level6/index.rst diff --git a/docs/demo/level1/level2/level3/level4/level5/level6/index.rst b/docs/demo/level1/level2/level3/level4/level5/level6/index.rst new file mode 100644 index 0000000..c9419dd --- /dev/null +++ b/docs/demo/level1/level2/level3/level4/level5/level6/index.rst @@ -0,0 +1,4 @@ + +****************** +Breadcrumb Level 6 +****************** diff --git a/docs/demo/lists_tables.rst b/docs/demo/lists_tables.rst new file mode 100644 index 0000000..d63cf47 --- /dev/null +++ b/docs/demo/lists_tables.rst @@ -0,0 +1,371 @@ + +************** +Lists & Tables +************** + +.. contents:: Table of Contents + +Lists +===== + +Enumerated Lists +---------------- + +1. Arabic numerals. + + a) lower alpha) + + (i) (lower roman) + + A. upper alpha. + + I) upper roman) + +2. Lists that don't start at 1: + + 3. Three + + 4. Four + + C. C + + D. D + + iii. iii + + iv. iv + +#. List items may also be auto-enumerated. + +Definition Lists +---------------- + +Term + Definition +Term : classifier + Definition paragraph 1. + + Definition paragraph 2. +Term + Definition + +I have no clue why the definition list below is classified as a different style +of definition list than the one above. + +Is it the spaces in the term? + Maybe it was the multiple line paragraph + in the line below that caused this? + +Is it the paragraph above the list maybe? + I guess a lot of these lists don't have leading paragraphs? + +Is it everything all at once? + Who knows?! + +Option Lists +------------ + +For listing command-line options: + +-a command-line option "a" +-b file options can have arguments + and long descriptions +--long options can be long also +--input=file long options can also have + arguments + +--very-long-option + The description can also start on the next line. + + The description may contain multiple body elements, + regardless of where it starts. + +-x, -y, -z Multiple options are an "option group". +-v, --verbose Commonly-seen: short & long options. +-1 file, --one=file, --two file + Multiple options with arguments. +/V DOS/VMS-style options too + +There must be at least two spaces between the option and the description. + +Field list +---------- + +.. bibliographic fields (which also require a transform): + +:Author: David Goodger +:Address: 123 Example Street + Example, EX Canada + A1B 2C3 +:Contact: docutils-develop@lists.sourceforge.net +:Authors: Me; Myself; I +:organization: humankind +:date: $Date: 2012-01-03 19:23:53 +0000 (Tue, 03 Jan 2012) $ +:status: This is a "work in progress" +:revision: $Revision: 7302 $ +:version: 1 +:copyright: This document has been placed in the public domain. You + may do with it as you wish. You may copy, modify, + redistribute, reattribute, sell, buy, rent, lease, + destroy, or improve it, quote it at length, excerpt, + incorporate, collate, fold, staple, or mutilate it, or do + anything else to it that your or anyone else's heart + desires. +:field name: This is a generic bibliographic field. +:field name 2: + Generic bibliographic fields may contain multiple body elements. + + Like this. + +:Dedication: + + For Docutils users & co-developers. + +:abstract: + + This document is a demonstration of the reStructuredText markup + language, containing examples of all basic reStructuredText + constructs and many advanced constructs. + +Bullet Lists +------------ + +.. + Docutils supports two types of lists, "simple" and "complex". Complex lists + have item margins, simple lists do not. + https://docutils.sourceforge.io/sandbox/html4strict/data/simple-lists.html + +Simple +^^^^^^ + +- A simple list. +- There are no margins between list items. +- Simple lists do not contain multiple paragraphs. That's a complex list. +- In the case of a nested list + + - There are no margins between elements + + - Still no margins + + - Still no margins + +Complex +^^^^^^^ + +- A bullet list + + + Nested bullet list. + + Nested item 2. + +- Item 2. + + Paragraph 2 of item 2. + + * Nested bullet list. + * Nested item 2. + + - Third level. + - Item 2. + + * Nested item 3. + +- ``inline literall`` +- ``inline literall`` +- ``inline literall`` +- This item has multiple paragraphs. + + This item has multiple paragraphs. +- This item has multiple paragraphs. + + This item has multiple paragraphs. + + +Second list level +^^^^^^^^^^^^^^^^^ + +- here is a list in a second-level section. +- `yahoo `_ +- `yahoo `_ + + - `yahoo `_ + - here is an inner bullet ``oh`` + + - one more ``with an inline literally``. `yahoo `_ + + heh heh. child. try to beat this embed: + + .. literalinclude:: test_py_module/test.py + :language: python + :linenos: + :lines: 1-10 + - and another. `yahoo `_ + - `yahoo `_ + - ``hi`` +- how about an admonition? + + .. note:: + This is a note nested in a list. + +- and hehe + +But deeper down the rabbit hole +""""""""""""""""""""""""""""""" + +- I kept saying that, "deeper down the rabbit hole". `yahoo `_ + + - I cackle at night `yahoo `_. +- I'm so lonely here in GZ ``guangzhou`` +- A man of python destiny, hopes and dreams. `yahoo `_ + + - `yahoo `_ + + - `yahoo `_ ``hi`` + - ``destiny`` + +Hlists +------ + +.. hlist:: + :columns: 2 + + - First item + - Second item + - Third item + - Forth item + - Fifth item + - Sixths item + +.. rubric:: Hlist with images + +.. hlist:: + :columns: 2 + + - .. figure:: static/yi_jing_01_chien.jpg + + This is a short caption for a figure. + + - .. figure:: static/yi_jing_01_chien.jpg + + This is a long caption for a figure. Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Donec porttitor dolor in odio posuere, vitae ornare libero mattis. In lobortis justo vestibulum nibh aliquet, non. + +Numbered List +------------- + +#. One, +#. Two. +#. Three with long text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Sed feugiat sagittis neque quis eleifend. Duis rutrum lectus sit amet mattis suscipit. + +- A) Using bullets and letters. (A) +- B) Using bullets and letters. (B) +- C) Using bullets and letters. (C) + +Tables +====== + +Grid Tables +----------- + +Here's a grid table followed by a simple table: + ++------------------------+------------+----------+----------+ +| Header row, column 1 | Header 2 | Header 3 | Header 4 | +| (header rows optional) | | | | ++========================+============+==========+==========+ +| body row 1, column 1 | column 2 | column 3 | column 4 | ++------------------------+------------+----------+----------+ +| body row 2 | Cells may span columns. | ++------------------------+------------+---------------------+ +| body row 3 | Cells may | - Table cells | ++------------------------+ span rows. | - contain | +| body row 4 | | - body elements. | ++------------------------+------------+----------+----------+ +| body row 5 | Cells may also be | | +| | empty: ``-->`` | | ++------------------------+-----------------------+----------+ + +===== ===== ====== + Inputs Output +------------ ------ + A B A or B +===== ===== ====== +False False False +True False True +False True True +True True True +===== ===== ====== + +Giant Tables +^^^^^^^^^^^^ + ++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+ +| Header 1 | Header 2 | Header 3 | Header 1 | Header 2 | Header 3 | Header 1 | Header 2 | Header 3 | Header 1 | Header 2 | Header 3 | ++============+============+===========+============+============+===========+============+============+===========+============+============+===========+ +| body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | ++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+ +| body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | ++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+ +| body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | ++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+ +| body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | body row 1 | column 2 | column 3 | ++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+ + +List Tables +----------- + +.. list-table:: List tables can have captions like this one. + :widths: 10 5 10 50 + :header-rows: 1 + :stub-columns: 1 + + * - List table + - Header 1 + - Header 2 + - Header 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu. + * - Stub Row 1 + - Row 1 + - Column 2 + - Column 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu. + * - Stub Row 2 + - Row 2 + - Column 2 + - Column 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu. + * - Stub Row 3 + - Row 3 + - Column 2 + - Column 3 long. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam sit amet mauris arcu. + +.. list-table:: This is a list table with images in it. + + * - .. figure:: static/yi_jing_01_chien.jpg + + This is a short caption for a figure. + + - .. figure:: static/yi_jing_01_chien.jpg + + This is a long caption for a figure. Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Donec porttitor dolor in odio posuere, vitae ornare libero mattis. In lobortis justo vestibulum nibh aliquet, non. + + +Tables with paragraphs +---------------------- + +.. regression test for https://github.com/readthedocs/sphinx_rtd_theme/issues/289 + +Test to see that tables behave well with nested paragraphs. + ++------------+----------+-------------------------+ +| Precedence | Operator | Description | ++============+==========+=========================+ +| 1 | \:: | Scope resolution | ++------------+----------+-------------------------+ +| 2 | ( ) | Function call | +| | | | +| | [ ] | Subscript | +| | | | +| | . | Member access | +| | | | +| | .{ } | Bit-field concatenation | ++------------+----------+-------------------------+ + diff --git a/docs/demo/long.rst b/docs/demo/long.rst new file mode 100644 index 0000000..26b1add --- /dev/null +++ b/docs/demo/long.rst @@ -0,0 +1,214 @@ + +*************** +Long Sticky Nav +*************** + +.. contents:: Table of Contents + +This section demonstrates how the 'sticky_navigation' setting behaves when the menu is very long. +When this section is selected, it will make the menu and the main area scroll when you are at the top of the page. + + +Example Menu 1 +============== + +Just a place holder... + + +Example Menu 2 +============== + +Just a place holder... + + +Example Menu 3 +============== + +Just a place holder... + + +Example Menu 4 +============== + +Just a place holder... + + +Example Menu 5 +============== + +Just a place holder... + + +Example Menu 6 +============== + +Just a place holder... + + +Example Menu 7 +============== + +Just a place holder... + + +Example Menu 8 +============== + +Just a place holder... + + +Example Menu 9 +============== + +Just a place holder... + + +Example Menu 10 +=============== + +Just a place holder... + + +Example Menu 11 +=============== + +Just a place holder... + + +Example Menu 12 +=============== + +Just a place holder... + + +Example Menu 13 +=============== + +Just a place holder... + + +Example Menu 14 +=============== + +Just a place holder... + + +Example Menu 15 +=============== + +Just a place holder... + + +Example Menu 16 +=============== + +Just a place holder... + + +Example Menu 17 +=============== + +Just a place holder... + + +Example Menu 18 +=============== + +Just a place holder... + + +Example Menu 19 +=============== + +Just a place holder... + + +Example Menu 20 +=============== + +Just a place holder... + +Example Submenu 1 +================= + +Just a place holder... + +Submenu 1 +--------- + +Just a place holder... + +Subsubmenu 1 +^^^^^^^^^^^^ + +Just a place holder... + +Subsubmenu 2 +^^^^^^^^^^^^ + +Just a place holder... + +Submenu 2 +--------- + +Just a place holder... + +Subsubmenu 1 +^^^^^^^^^^^^ + +Just a place holder... + +Submenu 3 +--------- + +Just a place holder... + +Submenu 4 +--------- + +Just a place holder... + +Submenu 5 +--------- + +Just a place holder... + +Example Submenu 2 +================= + +Just a place holder... + +Submenu 1 +--------- + +Just a place holder... + +Subsubmenu 1 +^^^^^^^^^^^^ + +Just a place holder... + +Submenu 2 +--------- + +Just a place holder... + +Subsubmenu 1 +^^^^^^^^^^^^ + +Just a place holder... + +Submenu 3 +--------- + +Just a place holder... + +Submenu 4 +--------- + +Just a place holder... + +Submenu 5 +--------- + +Just a place holder... diff --git a/docs/demo/static/favicon.ico b/docs/demo/static/favicon.ico new file mode 100644 index 0000000..42e8969 Binary files /dev/null and b/docs/demo/static/favicon.ico differ diff --git a/docs/demo/static/logo-wordmark-light.svg b/docs/demo/static/logo-wordmark-light.svg new file mode 100644 index 0000000..d0cbb66 --- /dev/null +++ b/docs/demo/static/logo-wordmark-light.svg @@ -0,0 +1,134 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/demo/static/screen_desktop.png b/docs/demo/static/screen_desktop.png new file mode 100644 index 0000000..dae4585 Binary files /dev/null and b/docs/demo/static/screen_desktop.png differ diff --git a/docs/demo/static/screen_mobile.png b/docs/demo/static/screen_mobile.png new file mode 100644 index 0000000..2383b7c Binary files /dev/null and b/docs/demo/static/screen_mobile.png differ diff --git a/docs/demo/static/yi_jing_01_chien.jpg b/docs/demo/static/yi_jing_01_chien.jpg new file mode 100644 index 0000000..523dc2b Binary files /dev/null and b/docs/demo/static/yi_jing_01_chien.jpg differ diff --git a/docs/demo/structure.rst b/docs/demo/structure.rst new file mode 100644 index 0000000..178ed63 --- /dev/null +++ b/docs/demo/structure.rst @@ -0,0 +1,101 @@ + +******************* +Structural Elements +******************* + +.. contents:: Table of Contents + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec, +finibus dictum velit. Ut eu efficitur arcu, id aliquam erat. In sit amet diam gravida, imperdiet tellus eu, +gravida nisl. Praesent aliquet odio eget libero elementum, quis rhoncus tellus tincidunt. +Suspendisse quis volutpat ipsum. Sed lobortis scelerisque tristique. Aenean condimentum risus tellus, +quis accumsan ipsum laoreet ut. Integer porttitor maximus suscipit. Mauris in posuere sapien. +Aliquam accumsan feugiat ligula, nec fringilla libero commodo sed. Proin et erat pharetra. + +--------- + +Etiam turpis ante, luctus sed velit tristique, finibus volutpat dui. Nam sagittis vel ante nec malesuada. +Praesent dignissim mi nec ornare elementum. Nunc eu augue vel sem dignissim cursus sed et nulla. +Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. +Pellentesque dictum dui sem, non placerat tortor rhoncus in. Sed placerat nulla at rhoncus iaculis. + +Document Section +================ + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed condimentum nulla vel neque venenatis, +nec placerat lorem placerat. Cras purus eros, gravida vitae tincidunt id, vehicula nec nulla. +Fusce aliquet auctor cursus. Phasellus ex neque, vestibulum non est vitae, viverra fringilla tortor. +Donec vestibulum convallis justo, a faucibus lorem vulputate vel. Aliquam cursus odio eu felis sodales aliquet. +Aliquam erat volutpat. Maecenas eget dictum mauris. Suspendisse arcu eros, condimentum eget risus sed, +luctus efficitur arcu. Cras ut dictum mi. Nulla congue interdum lorem, semper semper enim commodo nec. + +Document Subsection +------------------- + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam efficitur in eros et blandit. Nunc maximus, +nisl at auctor vestibulum, justo ex sollicitudin ligula, id faucibus urna orci tristique nisl. +Duis auctor rutrum orci, in ornare lacus condimentum quis. Quisque arcu velit, facilisis quis interdum ac, +hendrerit auctor mauris. Curabitur urna nibh, porttitor at ante sit amet, vestibulum interdum dolor. +Duis dictum elit orci, tincidunt imperdiet sem pellentesque et. In vehicula pellentesque varius. +Phasellus a turpis sollicitudin, bibendum massa et, imperdiet neque. Integer quis sapien in magna rutrum bibendum. +Integer cursus ex sed magna vehicula finibus. Proin tempus orci quis dolor tempus, nec condimentum odio vestibulum. +Etiam efficitur sollicitudin libero, tincidunt volutpat ligula interdum sed. + +Document Subsubsection +^^^^^^^^^^^^^^^^^^^^^^ + +Donec non rutrum lorem. Aenean sagittis metus at pharetra fringilla. Nunc sapien dolor, cursus sed nisi at, +pretium tristique lectus. Sed pellentesque leo lectus, et convallis ipsum euismod a. +Integer at leo vitae felis pretium aliquam fringilla quis odio. Sed pharetra enim accumsan feugiat pretium. +Maecenas at pharetra tortor. Morbi semper eget mi vel finibus. Cras rutrum nulla eros, id feugiat arcu pellentesque ut. +Sed finibus tortor ac nisi ultrices viverra. Duis feugiat malesuada sapien, at commodo ante porttitor ac. +Curabitur posuere mauris mi, vel ornare orci scelerisque sit amet. Suspendisse nec fringilla dui. + +Document Paragraph +"""""""""""""""""" + +Pellentesque nec est in odio ultrices elementum. Vestibulum et hendrerit sapien, quis vulputate turpis. +Suspendisse potenti. Curabitur tristique sit amet lectus non viverra. Phasellus rutrum dapibus turpis sed imperdiet. +Mauris maximus viverra ante. Donec eu egestas mauris. Morbi vulputate tincidunt euismod. Integer vel porttitor neque. +Donec at lacus suscipit, lacinia lectus vel, sagittis lectus. + +********************* +Structural Elements 2 +********************* + +Etiam turpis ante, luctus sed velit tristique, finibus volutpat dui. Nam sagittis vel ante nec malesuada. +Praesent dignissim mi nec ornare elementum. Nunc eu augue vel sem dignissim cursus sed et nulla. +Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. +Pellentesque dictum dui sem, non placerat tortor rhoncus in. Sed placerat nulla at rhoncus iaculis. + +Document Section +================ + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed condimentum nulla vel neque venenatis, +nec placerat lorem placerat. Cras purus eros, gravida vitae tincidunt id, vehicula nec nulla. +Fusce aliquet auctor cursus. Phasellus ex neque, vestibulum non est vitae, viverra fringilla tortor. +Donec vestibulum convallis justo, a faucibus lorem vulputate vel. Aliquam cursus odio eu felis sodales aliquet. +Aliquam erat volutpat. Maecenas eget dictum mauris. Suspendisse arcu eros, condimentum eget risus sed, +luctus efficitur arcu. Cras ut dictum mi. Nulla congue interdum lorem, semper semper enim commodo nec. + +Document Subsection +------------------- + +.. figure:: static/yi_jing_01_chien.jpg + :align: right + :figwidth: 200px + + This is a caption for a figure. Text should wrap around the caption. + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam efficitur in eros et blandit. Nunc maximus, +nisl at auctor vestibulum, justo ex sollicitudin ligula, id faucibus urna orci tristique nisl. +Duis auctor rutrum orci, in ornare lacus condimentum quis. Quisque arcu velit, facilisis quis interdum ac, +hendrerit auctor mauris. Curabitur urna nibh, porttitor at ante sit amet, vestibulum interdum dolor. +Duis dictum elit orci, tincidunt imperdiet sem pellentesque et. In vehicula pellentesque varius. +Phasellus a turpis sollicitudin, bibendum massa et, imperdiet neque. Integer quis sapien in magna rutrum bibendum. +Integer cursus ex sed magna vehicula finibus. Proin tempus orci quis dolor tempus, nec condimentum odio vestibulum. +Etiam efficitur sollicitudin libero, tincidunt volutpat ligula interdum sed. Praesent congue sagittis nisl et suscipit. +Vivamus sagittis risus et egestas commodo.Cras venenatis arcu in pharetra interdum. +Donec quis metus porttitor tellus cursus lobortis. Quisque et orci magna. Fusce rhoncus mi mi, +at vehicula massa rhoncus quis. Mauris augue leo, pretium eget molestie vitae, efficitur nec nulla. +In hac habitasse platea dictumst. Sed sit amet imperdiet purus. diff --git a/docs/demo/test_py_module/__init__.py b/docs/demo/test_py_module/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/docs/demo/test_py_module/test.py b/docs/demo/test_py_module/test.py new file mode 100644 index 0000000..426ec61 --- /dev/null +++ b/docs/demo/test_py_module/test.py @@ -0,0 +1,148 @@ +# -*- coding: utf-8 -*- +"""Test Module for sphinx_rtd_theme.""" + + +class Foo: + + """Docstring for class Foo. + + This text tests for the formatting of docstrings generated from output + ``sphinx.ext.autodoc``. Which contain reST, but sphinx nests it in the + ``
``, and ``
`` tags. Also, ```` is used for class, method names + and etc, but those will *always* have the ``.descname`` or + ``.descclassname`` class. + + Term + It is also possible to include definitions inside docstrings. + They should be styled as a normal definition list. + + :Field List: + It is also possible to include definitions inside docstrings. + They should be styled as a normal definition list. + + .. [1] A footnote contains body elements, consistently indented by at + least 3 spaces. + + .. [Citation] A citation contains body elements, consistently indented by at + least 3 spaces. + + Normal ```` (like the I just wrote here) needs to be shown with + the same style as anything else with ````this type of markup````. + + It's common for programmers to give a code example inside of their + docstring:: + + from test_py_module import Foo + + myclass = Foo() + myclass.dothismethod('with this argument') + myclass.flush() + + print(myclass) + + + Here is a link to :py:meth:`capitalize`. + Here is a link to :py:meth:`__init__`. + + """ + + #: Doc comment for class attribute Foo.bar. + #: It can have multiple lines. + bar = 1 + + flox = 1.5 #: Doc comment for Foo.flox. One line only. + + baz = 2 + """Docstring for class attribute Foo.baz.""" + + def __init__(self, qux, spam=False): + """Start the Foo. + + :param qux: The first argument to initialize class. + :type qux: string + :param spam: Spam me yes or no... + :type spam: bool + + """ + #: Doc comment for instance attribute qux. + self.qux = 3 + + self.spam = 4 + """Docstring for instance attribute spam.""" + + def add(self, val1, val2): + """Return the added values. + + :param val1: First number to add. + :type val1: int + :param val2: Second number to add. + :type val2: int + :rtype: int + + The parameters of this method are described in the parameter list. + """ + + return val1 + val2 + + def capitalize(self, myvalue): + """Return a string as uppercase. + + :param myvalue: String to change + :type myvalue: string + :rtype: string + + """ + + return myvalue.upper() + + def another_function(self, a, b, **kwargs): + """ + Here is another function. + + :param a: The number of green hats you own. + :type a: int + + :param b: The number of non-green hats you own. + :type b: int + + :param kwargs: Additional keyword arguments. Each keyword parameter + should specify the name of your favorite cuisine. + The values should be floats, specifying the mean price + of your favorite dish in that cooking style. + :type kwargs: float + + :returns: A 2-tuple. The first element is the mean price of all dishes + across cuisines. The second element is the total number of + hats you own: :math:`a + b`. + :rtype: tuple + + :raises ValueError: When ``a`` is not an integer. + + .. versionadded:: 1.0 + This was added in 1.0 + .. versionchanged:: 2.0 + This was changed in 2.0 + .. deprecated:: 3.0 + This is deprecated since 3.0 + """ + return sum(kwargs.values()) / len(kwargs), a + b + + +def add_numbers(a: int, b: int = 0) -> int: + """Add two numbers together + + :param a: The first number + :param b: The second number + + Here is some more text. + """ + return a + b + + +def subtract_numbers(a: int, b: int = 0) -> int: + """Subtract two numbers + + :param a: The first number + :param b: The second number + """ + return a - b -- cgit v1.2.3