diff --git a/.circleci/config.yml b/.circleci/config.yml index 1a62df043..0ad80c4d5 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -28,7 +28,7 @@ jobs: conda update conda conda config --add channels conda-forge # Install pandas + some optional dependencies - conda install pandas matplotlib ipython sphinx ipykernel jinja2 numpydoc nbconvert nbsphinx jupyter_client gitpython + pip install -r docs/requirements.txt # install the theme package pip install -e . # Cache some files for a speedup in subsequent builds @@ -41,11 +41,11 @@ jobs: name: Build docs to store command: | export PATH="$HOME/miniconda/bin:$PATH" - cd pandas-docs - python make.py html + cd docs + make html # Tell Circle to store the documentation output in a folder that we can access later - store_artifacts: - path: pandas-docs/build/html/ + path: docs/_build/html/ destination: html # Tell CircleCI to use this workflow when it builds the site diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..1b5645be6 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= --keep-going +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +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) diff --git a/docs/_static/pandas.svg b/docs/_static/pandas.svg new file mode 100644 index 000000000..a7af4e4d2 --- /dev/null +++ b/docs/_static/pandas.svg @@ -0,0 +1 @@ +Artboard 63 \ No newline at end of file diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 000000000..c04c0db13 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,11 @@ +********* +Changelog +********* + +master +====== + +New Features +------------- + +* The theme now exists... \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..6ddb618f3 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,59 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- 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 = 'Pandas Sphinx Theme' +copyright = '2019, PyData Community' +author = 'PyData Community' + +# The full version, including alpha/beta/rc tags +release = '0.0.1dev0' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# 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 = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- 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 = 'pandas_sphinx_theme' +html_logo = '_static/pandas.svg' + +# 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'] \ No newline at end of file diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 000000000..87127441a --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,5 @@ +************ +Contributing +************ + +TODO diff --git a/docs/demo/api.rst b/docs/demo/api.rst new file mode 100644 index 000000000..4036266b5 --- /dev/null +++ b/docs/demo/api.rst @@ -0,0 +1,159 @@ +*************************************** +API documentation and generated content +*************************************** + +This page contains general code elements that are common +for package documentation. + +.. contents:: Table of Contents + +Pandas DataFrame +================ + +.. currentmodule:: pandas + +.. autosummary:: + :toctree: api/ + + DataFrame + DataFrame.index + DataFrame.columns + DataFrame.dtypes + DataFrame.ftypes + DataFrame.get_dtype_counts + DataFrame.get_ftype_counts + DataFrame.select_dtypes + DataFrame.values + + +:mod:`pandas.datetime` +====================== + +.. automodule:: pandas.datetime + :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 in generate and 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`. diff --git a/docs/demo/demo.rst b/docs/demo/demo.rst new file mode 100644 index 000000000..6d3afae91 --- /dev/null +++ b/docs/demo/demo.rst @@ -0,0 +1,475 @@ +.. 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 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 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 can be used to show short 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. + +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 +--------- + +.. [11] 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, [12]_, and a [nonexistent]_ citation. + +Here is another type of citation: `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 `Body Elements`_. + +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/index.rst b/docs/demo/index.rst new file mode 100644 index 000000000..f93aab22a --- /dev/null +++ b/docs/demo/index.rst @@ -0,0 +1,24 @@ +========= +Demo site +========= + +This is a simple demonstration site to show off a few visual +and structural elements of the theme. Click the sections on +the left sidebar to see how various elements look on this theme. + +.. toctree:: + :maxdepth: 2 + :numbered: + :caption: Demo Documentation + + structure + api + demo + lists_tables + +.. toctree:: + :maxdepth: 3 + :numbered: + :caption: This is an incredibly long caption for a long menu + + long diff --git a/docs/demo/lists_tables.rst b/docs/demo/lists_tables.rst new file mode 100644 index 000000000..4c7642e5c --- /dev/null +++ b/docs/demo/lists_tables.rst @@ -0,0 +1,302 @@ + +************** +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 + + +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 +------------ + +- 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`` + +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`` +- 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. diff --git a/docs/demo/long.rst b/docs/demo/long.rst new file mode 100644 index 000000000..26b1add9d --- /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/logo-wordmark-light.svg b/docs/demo/static/logo-wordmark-light.svg new file mode 100644 index 000000000..d0cbb66a1 --- /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 000000000..dae4585e5 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 000000000..2383b7c45 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 000000000..523dc2b8b 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 000000000..178ed63f0 --- /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 000000000..e69de29bb diff --git a/docs/demo/test_py_module/test.py b/docs/demo/test_py_module/test.py new file mode 100644 index 000000000..f47b9840c --- /dev/null +++ b/docs/demo/test_py_module/test.py @@ -0,0 +1,113 @@ +# -*- 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. + + 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 + + """ + + 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 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..d3815ec82 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,22 @@ +======================= +The Pandas Sphinx Theme +======================= + +This is a simple Sphinx theme for use by the Pandas and +PyData community. This site is a guide for using the theme, +and a demo for how it looks with various elements. + +.. toctree:: + :caption: Theme Documentation + :maxdepth: 2 + + user_guide/index + contributing + +.. toctree:: + :maxdepth: 2 + :hidden: + + demo/index + changelog + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 000000000..2119f5109 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..fa290335b --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx +pandas diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst new file mode 100644 index 000000000..a432c733b --- /dev/null +++ b/docs/user_guide/configuring.rst @@ -0,0 +1,5 @@ +************* +Configuration +************* + +TODO diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst new file mode 100644 index 000000000..9740b60b1 --- /dev/null +++ b/docs/user_guide/index.rst @@ -0,0 +1,10 @@ +========== +User Guide +========== + + +.. toctree:: + :maxdepth: 2 + + install + configuring diff --git a/docs/user_guide/install.rst b/docs/user_guide/install.rst new file mode 100644 index 000000000..395b5ec75 --- /dev/null +++ b/docs/user_guide/install.rst @@ -0,0 +1,25 @@ +************ +Installation +************ + +This theme is not yet released as a package on PyPI, so for now you need to +install it from the git repo. You can do this with pip: + +.. code:: console + + $ pip install git+https://github.com/pandas-dev/pandas-sphinx-theme.git@master + +or in a conda environment yml file, you can add: + +.. code:: none + + - pip: + - git+https://github.com/pandas-dev/pandas-sphinx-theme.git@master + + +Then, in the ``conf.py`` of your sphinx docs, you update the ``html_theme`` +configuration option: + +.. code:: python + + html_theme = "pandas_sphinx_theme"