diff --git a/doc/Makefile b/doc/Makefile index 372dc121..7c277ffb 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -6,15 +6,24 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build SPHINXPROJ = cismdoc SOURCEDIR = source +DIRWITHCONFPY = doc-builder BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +# 'make fetch-images' should be run before building the documentation. (If building via +# the build_docs command, this is run automatically for you.) This is needed because we +# have configured this repository (via an .lfsconfig file at the top level) to NOT +# automatically fetch any of the large files when cloning / fetching. +fetch-images: + git lfs install --force + git lfs pull --exclude="" --include="" + +.PHONY: help fetch-images Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" $(SPHINXOPTS) $(O) diff --git a/doc/build_docs b/doc/build_docs new file mode 100755 index 00000000..99415e15 --- /dev/null +++ b/doc/build_docs @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +set -e + +if [ ! -f doc-builder/build_docs ]; then + script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" + ${script_dir}/../bin/git-fleximod update doc-builder +fi + +# Check if --verbose or -V was passed +verbose=false +for arg in "$@"; do + case "$arg" in + --verbose|-V) verbose=true; break ;; + esac +done + +if $verbose; then + echo "Running: make fetch-images" + make fetch-images +else + make fetch-images > /dev/null 2>&1 +fi + +if $verbose; then + echo "Running: ./doc-builder/build_docs $@" +fi +./doc-builder/build_docs "$@" + +exit 0 diff --git a/doc/build_docs_to_publish b/doc/build_docs_to_publish new file mode 100755 index 00000000..bc4075c9 --- /dev/null +++ b/doc/build_docs_to_publish @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +set -e + +script_dir="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" +if [ ! -f doc-builder/build_docs_to_publish ]; then + "${script_dir}"/../bin/git-fleximod update doc-builder +fi + +# Check if --verbose or -V was passed +verbose=false +for arg in "$@"; do + case "$arg" in + --verbose|-V) verbose=true; break ;; + esac +done + +cd "${script_dir}" + +if $verbose; then + echo "Running: make fetch-images" + make fetch-images +else + make fetch-images > /dev/null 2>&1 +fi + +if $verbose; then + echo "Running: ./doc-builder/build_docs_to_publish $@" + pwd +fi +./doc-builder/build_docs_to_publish "$@" + +exit 0 diff --git a/doc/source/_themes/sphinx_rtd_theme/README.rst b/doc/source/_themes/sphinx_rtd_theme/README.rst deleted file mode 100644 index f3e791e0..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/README.rst +++ /dev/null @@ -1,315 +0,0 @@ -.. _readthedocs.org: http://www.readthedocs.org -.. _bower: http://www.bower.io -.. _sphinx: http://www.sphinx-doc.org -.. _compass: http://www.compass-style.org -.. _sass: http://www.sass-lang.com -.. _wyrm: http://www.github.com/snide/wyrm/ -.. _grunt: http://www.gruntjs.com -.. _node: http://www.nodejs.com -.. _demo: http://docs.readthedocs.org -.. _hidden: http://sphinx-doc.org/markup/toctree.html - -************************** -Read the Docs Sphinx Theme -************************** - -.. contents:: - -View a working demo_ over on readthedocs.org_. - -This is a mobile-friendly sphinx_ theme I made for readthedocs.org_. - -If you'd like to update the theme, -please make your edits to the SASS files here, -rather than the .css files on checked into the repo. - -.. image:: demo_docs/source/static/screen_mobile.png - :width: 100% - -Installation -============ - -Via package ------------ - -Download the package or add it to your ``requirements.txt`` file: - -.. code:: bash - - pip install sphinx_rtd_theme - -In your ``conf.py`` file: - -.. code:: python - - import sphinx_rtd_theme - html_theme = "sphinx_rtd_theme" - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -or (since v0.2.5): - -.. code:: python - - html_theme = "sphinx_rtd_theme" - -Via git or download -------------------- - -Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at -``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx -``conf.py`` file: - -.. code:: python - - html_theme = "sphinx_rtd_theme" - html_theme_path = ["_themes", ] - -Configuration -============= - -You can configure different parts of the theme. - -Project-wide configuration --------------------------- - -The theme's project-wide options are defined in the ``sphinx_rtd_theme/theme.conf`` -file of this repository, and can be defined in your project's ``conf.py`` via -``html_theme_options``. For example: - -.. code:: python - - html_theme_options = { - 'collapse_navigation': False, - 'display_version': False, - 'navigation_depth': 3, - 'versions': { - '1.0': 'https://example.com/1.0/', - '2.0': 'https://example.com/2.0/', - } - } - -The following options are available: - -``canonical_url`` - This will specify a `canonical url - `__ to let search - engines know they should give higher ranking to latest version of the - docs. The url points to the root of the documentation and requires a - trailing slash. - -``versions`` - This option should be defined as a dictionary of versions, where the key - is the version slug and the value is the URL. This will enable a version - dropdown at the top of the menu. - - .. note:: - This is disabled on Read the Docs currently - -Page-level configuration ------------------------- - -Pages support metadata that changes how the theme renders. -You can currently add the following: - -``:github_url:`` - This will force the "Edit on GitHub" to the configured URL - -``:bitbucket_url:`` - This will force the "Edit on Bitbucket" to the configured URL - -``:gitlab_url:`` - This will force the "Edit on GitLab" to the configured URL - -Changelog -========= - -master ------- - -* Include fontawesome-webfont.woff2 in pip package -* Updated wyrm_ and Font Awesome -* Split multiple data types on different lines -* Italicize ``.versionmodified`` -* Fix line number spacing to align with the code lines -* Hide Edit links on auto created pages -* Align ``.. centered::`` text to the center -* Increase contrast for footnotes -* Add language to the JS output variable -* Include the lato italics font with the theme -* Fix padding on field lists -* Add setuptools entry point allowing to use ``sphinx_rtd_theme`` as - Sphinx ``html_theme`` directly. -* Add version dropdown select - -v0.2.4 ------- - -* Yet another patch to deal with extra builders outside Spinx, such as the - singlehtml builders from the Read the Docs Sphinx extension - -v0.2.3 ------- - -* Temporarily patch Sphinx issue with ``singlehtml`` builder by inspecting the - builder in template. - -v0.2.2 ------- - -* Roll back toctree fix in 0.2.1 (#367). This didn't fix the issue and - introduced another bug with toctrees display. - -v0.2.1 ------- - -* Add the ``rel`` HTML attribute to the footer links which point to - the previous and next pages. -* Fix toctree issue caused by Sphinx singlehtml builder (#367) - -v0.2.0 ------- - -* Adds the ``comments`` block after the ``body`` block in the template -* Added "Edit on GitLab" support -* Many bug fixes - -v0.1.10-alpha -------------- - -.. note:: This is a pre-release version - -* Removes Sphinx dependency -* Fixes hamburger on mobile display -* Adds a ``body_begin`` block to the template -* Add ``prev_next_buttons_location`` which can take the value ``bottom``, - ``top``, ``both`` , ``None`` and will display the "Next" and "Previous" - buttons accordingly - -v0.1.9 ------- - -* Intermittent scrollbar visibility bug fixed. This change introduces a - backwards incompatible change to the theme's layout HTML. This should only be - a problem for derivative themes that have overridden styling of nav elements - using direct decendant selectors. See `#215`_ for more information. -* Safari overscroll bug fixed -* Version added to the nav header -* Revision id was added to the documentation footer if you are using RTD -* An extra block, ``extrafooter`` was added to allow extra content in the - document footer block -* Fixed modernizr URL -* Small display style changes on code blocks, figure captions, and nav elements - -.. _#215: https://github.com/rtfd/sphinx_rtd_theme/pull/215 - -v0.1.8 ------- - -* Start keeping changelog :) -* Support for third and fourth level headers in the sidebar -* Add support for Sphinx 1.3 -* Add sidebar headers for :caption: in Sphinx toctree -* Clean up sidebar scrolling behavior so it never scrolls out of view - -How the Table of Contents builds -================================ - -Currently the left menu will build based upon any ``toctree(s)`` defined in your ``index.rst`` file. -It outputs 2 levels of depth, which should give your visitors a high level of access to your -docs. If no toctrees are set the theme reverts to sphinx's usual local toctree. - -It's important to note that if you don't follow the same styling for your rST headers across -your documents, the toctree will misbuild, and the resulting menu might not show the correct -depth when it renders. - -Also note that the table of contents is set with ``includehidden=true``. This allows you -to set a hidden toc in your index file with the hidden_ property that will allow you -to build a toc without it rendering in your index. - -By default, the navigation will "stick" to the screen as you scroll. However if your toc -is vertically too large, it will revert to static positioning. To disable the sticky nav -altogether change the setting in ``conf.py``. - -Contributing or modifying the theme -=================================== - -The sphinx_rtd_theme is primarily a sass_ project that requires a few other sass libraries. I'm -using bower_ to manage these dependencies and sass_ to build the css. The good news is -I have a very nice set of grunt_ operations that will not only load these dependencies, but watch -for changes, rebuild the sphinx demo docs and build a distributable version of the theme. -The bad news is this means you'll need to set up your environment similar to that -of a front-end developer (vs. that of a python developer). That means installing node and ruby. - -Set up your environment ------------------------ - -#. Install sphinx_ into a virtual environment. - - .. code:: bash - - pip install sphinx sphinxcontrib-httpdomain - -#. Install sass. - - .. code:: bash - - gem install sass - -#. Install node, bower, grunt, and theme dependencies. - - .. code:: bash - - # Install node - brew install node - - # Install bower and grunt - npm install -g bower grunt-cli - - # Now that everything is installed, let's install the theme dependencies. - npm install - -Now that our environment is set up, make sure you're in your virtual environment, go to -this repository in your terminal and run grunt: - -.. code:: - - grunt - -This default task will do the following **very cool things that make it worth the trouble**: - -#. Install and update any bower dependencies. -#. Run sphinx and build new docs. -#. Watch for changes to the sass files and build css from the changes. -#. Rebuild the sphinx docs anytime it notices a change to ``.rst``, ``.html``, ``.js`` - or ``.css`` files. - -Before you create an issue --------------------------- - -I don't have a lot of time to maintain this project due to other responsibilities. -I know there are a lot of Python engineers out there that can't code sass / css and -are unable to submit pull requests. That said, submitting random style bugs without -at least providing sample documentation that replicates your problem is a good -way for me to ignore your request. RST unfortunately can spit out a lot of things -in a lot of ways. I don't have time to research your problem for you, but I do -have time to fix the actual styling issue if you can replicate the problem for me. - -Releasing the Theme -=================== - -When you release a new version, -you should do the following: - -#. Bump the version in ``sphinx_rtd_theme/__init__.py`` – we try to follow `semver `_, so be careful with breaking changes. -#. Run a ``grunt build`` to rebuild all the theme assets. -#. Commit that change. -#. Tag the release in git: ``git tag $NEW_VERSION``. -#. Push the tag to GitHub: ``git push --tags origin``. -#. Upload the package to PyPI: ``python setup.py sdist bdist_wheel upload``. -#. In the ``readthedocs.org`` repo, edit the ``bower.json`` file to point at the correct version (``sphinx-rtd-theme": "https://github.com/rtfd/sphinx-rtd-theme.git#$NEW_VERSION"``). -#. In the ``readthedocs.org`` repo, run ``gulp build`` to update the distributed theme files. - -TODO -==== - -* Separate some sass variables at the theme level so you can overwrite some basic colors. diff --git a/doc/source/_themes/sphinx_rtd_theme/demo_docs/Makefile b/doc/source/_themes/sphinx_rtd_theme/demo_docs/Makefile deleted file mode 100644 index 8c907fd4..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/Makefile +++ /dev/null @@ -1,153 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxRTDthemedemo.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxRTDthemedemo.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxRTDthemedemo" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxRTDthemedemo" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/api.rst b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/api.rst deleted file mode 100644 index aa1834ff..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/api.rst +++ /dev/null @@ -1,48 +0,0 @@ - -********************* -:mod:`test_py_module` -********************* - -.. contents:: Table of Contents - -.. automodule:: test_py_module.test - :members: - :private-members: - :special-members: - - -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/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/conf.py b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/conf.py deleted file mode 100644 index 9a291a5c..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/conf.py +++ /dev/null @@ -1,262 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Sphinx RTD theme demo documentation build configuration file, created by -# sphinx-quickstart on Sun Nov 3 11:56:36 2013. -# -# This file is executed with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys -import os - -sys.path.append(os.path.abspath('.')) -sys.path.append(os.path.abspath('./test_py_module')) - -# 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. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.mathjax', - 'sphinx.ext.viewcode', - 'sphinxcontrib.httpdomain', -] - -# Math -mathjax_path = "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Sphinx RTD theme demo' -copyright = u'2013, Dave Snider' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.2.4' -# The full version, including alpha/beta/rc tags. -release = '0.2.4' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- 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 = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -html_theme_options = { - # 'sticky_navigation': True # Set to False to disable the sticky nav while scrolling. - # 'logo_only': True, # if we have a html_logo below, this shows /only/ the logo with no title text - 'versions': { - '1.0': '', - '2.0': '', - '2.1-beta-with-a-long-name': '', - } -} - -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = ["../.."] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = "static/logo-wordmark-light.svg" - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# 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'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'SphinxRTDthemedemodoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'SphinxRTDthemedemo.tex', u'Sphinx RTD theme demo Documentation', - u'Dave Snider', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'sphinxrtdthemedemo', u'Sphinx RTD theme demo Documentation', - [u'Dave Snider'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'SphinxRTDthemedemo', u'Sphinx RTD theme demo Documentation', - u'Dave Snider', 'SphinxRTDthemedemo', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' diff --git a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/demo.rst b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/demo.rst deleted file mode 100644 index 3ad6e46b..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/demo.rst +++ /dev/null @@ -1,475 +0,0 @@ -.. 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 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/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/index.rst b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/index.rst deleted file mode 100644 index c439b2cf..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/index.rst +++ /dev/null @@ -1,30 +0,0 @@ - -***************************** -Read the Docs Theme Demo Docs -***************************** - -These documents are used to test and stress test the Read the Docs Theme. - -:Last Reviewed: 2017-3-15 - -Contents -======== - -.. toctree:: - :maxdepth: 3 - :numbered: - :caption: Syntax Constructs - - structure - demo - lists_tables - api - -.. toctree:: - :maxdepth: 3 - :numbered: - :caption: This is an incredibly long caption for a long menu - - long - -You can also read the :ref:`genindex` diff --git a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/lists_tables.rst b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/lists_tables.rst deleted file mode 100644 index 4c7642e5..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/lists_tables.rst +++ /dev/null @@ -1,302 +0,0 @@ - -************** -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/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/long.rst b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/long.rst deleted file mode 100644 index 26b1add9..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/long.rst +++ /dev/null @@ -1,214 +0,0 @@ - -*************** -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/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/logo-wordmark-light.svg b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/logo-wordmark-light.svg deleted file mode 100644 index d0cbb66a..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/logo-wordmark-light.svg +++ /dev/null @@ -1,134 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/screen_desktop.png b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/screen_desktop.png deleted file mode 100644 index dae4585e..00000000 Binary files a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/screen_desktop.png and /dev/null differ diff --git a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/screen_mobile.png b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/screen_mobile.png deleted file mode 100644 index 2383b7c4..00000000 Binary files a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/screen_mobile.png and /dev/null differ diff --git a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/yi_jing_01_chien.jpg b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/yi_jing_01_chien.jpg deleted file mode 100644 index 523dc2b8..00000000 Binary files a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/static/yi_jing_01_chien.jpg and /dev/null differ diff --git a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/structure.rst b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/structure.rst deleted file mode 100644 index 178ed63f..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/structure.rst +++ /dev/null @@ -1,101 +0,0 @@ - -******************* -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/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/test_py_module/__init__.py b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/test_py_module/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/test_py_module/test.py b/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/test_py_module/test.py deleted file mode 100644 index f47b9840..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/test_py_module/test.py +++ /dev/null @@ -1,113 +0,0 @@ -# -*- 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/doc/source/_themes/sphinx_rtd_theme/tests/__init__.py b/doc/source/_themes/sphinx_rtd_theme/tests/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/bar.rst b/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/bar.rst deleted file mode 100644 index 1cccd3cb..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/bar.rst +++ /dev/null @@ -1,2 +0,0 @@ -bar -=== diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/conf.py b/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/conf.py deleted file mode 100644 index e10f5e5f..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/conf.py +++ /dev/null @@ -1,4 +0,0 @@ -# -*- coding: utf-8 -*- - -master_doc = 'index' -exclude_patterns = ['_build'] diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/foo.rst b/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/foo.rst deleted file mode 100644 index 468a4247..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/foo.rst +++ /dev/null @@ -1,6 +0,0 @@ -foo -=== - -.. toctree:: - - bar diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/index.rst b/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/index.rst deleted file mode 100644 index 0a4b3473..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -test-basic -========== - -.. toctree:: - - foo - -Heading -------- - -Subheading -~~~~~~~~~~ diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-empty/conf.py b/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-empty/conf.py deleted file mode 100644 index e10f5e5f..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-empty/conf.py +++ /dev/null @@ -1,4 +0,0 @@ -# -*- coding: utf-8 -*- - -master_doc = 'index' -exclude_patterns = ['_build'] diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-empty/index.rst b/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-empty/index.rst deleted file mode 100644 index a69c08db..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-empty/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -test-empty -========== - -.. toctree:: - -Heading -------- - -Subheading -~~~~~~~~~~ diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-missing-toctree/conf.py b/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-missing-toctree/conf.py deleted file mode 100644 index e10f5e5f..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-missing-toctree/conf.py +++ /dev/null @@ -1,4 +0,0 @@ -# -*- coding: utf-8 -*- - -master_doc = 'index' -exclude_patterns = ['_build'] diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-missing-toctree/index.rst b/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-missing-toctree/index.rst deleted file mode 100644 index a085e7ff..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-missing-toctree/index.rst +++ /dev/null @@ -1,2 +0,0 @@ -test-missing-toctree -==================== diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/test_builders.py b/doc/source/_themes/sphinx_rtd_theme/tests/test_builders.py deleted file mode 100644 index 3602782d..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/test_builders.py +++ /dev/null @@ -1,99 +0,0 @@ -import os - -import pytest -import sphinx -from sphinx import addnodes -from sphinx.builders.html import SingleFileHTMLBuilder, DirectoryHTMLBuilder - -from .util import build_all - - -def test_basic(): - for (app, status, warning) in build_all('test-basic'): - assert app.env.get_doctree('index').traverse(addnodes.toctree) - content = open(os.path.join(app.outdir, 'index.html')).read() - - if isinstance(app.builder, DirectoryHTMLBuilder): - search = ( - '
\n' - '
    \n' - '
  • ' - 'foo' - '
      \n' - '
    • ' - 'bar
      • \n' - '
    \n' - '
    • \n' - '
\n' - '
' - ) - assert search in content - elif isinstance(app.builder, SingleFileHTMLBuilder): - search = ( - '
    \n' - '
  • ' - 'foo' - '
      \n' - '
    • ' - 'bar' - '
      • \n' - '
    ' - ) - assert search in content - else: - search = ( - '
    \n' - '
      \n' - '
    • ' - 'foo' - '
        \n' - '
      • ' - 'bar
        • \n' - '
      \n' - '
      • \n' - '
    \n' - '
    ' - ) - assert search in content, ('Missing search with builder {0}' - .format(app.builder.name)) - - -def test_empty(): - """Local TOC is showing, as toctree was empty""" - for (app, status, warning) in build_all('test-empty'): - assert app.env.get_doctree('index').traverse(addnodes.toctree) - content = open(os.path.join(app.outdir, 'index.html')).read() - if sphinx.version_info < (1, 4): - if isinstance(app.builder, SingleFileHTMLBuilder): - assert '
    \n
    ' in content - assert '
    ' in content - else: - global_toc = ( - '
    \n' - '
      \n
    \n' - '
    ' - ) - local_toc = ( - '
      ' - '
    \n
    ' - ) - assert global_toc in content - assert local_toc not in content - else: - global_toc = '
    \n
    ' - local_toc = ( - '
    \n
    ' - ) - assert global_toc in content - assert local_toc not in content - - -def test_missing_toctree(): - """Local TOC is showing, as toctree was missing""" - for (app, status, warning) in build_all('test-missing-toctree'): - assert app.env.get_doctree('index').traverse(addnodes.toctree) == [] - content = open(os.path.join(app.outdir, 'index.html')).read() - assert '
    ' in content diff --git a/doc/source/_themes/sphinx_rtd_theme/tests/util.py b/doc/source/_themes/sphinx_rtd_theme/tests/util.py deleted file mode 100644 index cf81029b..00000000 --- a/doc/source/_themes/sphinx_rtd_theme/tests/util.py +++ /dev/null @@ -1,60 +0,0 @@ -from __future__ import print_function - -import os -import tempfile -import shutil -from contextlib import contextmanager - -import pytest -from sphinx.application import Sphinx - -try: - from StringIO import StringIO -except ImportError: - from io import StringIO - - -@contextmanager -def build(root, builder='html', **kwargs): - tmpdir = tempfile.mkdtemp() - - srcdir = os.path.join(os.path.dirname(__file__), 'roots', root) - destdir = os.path.join(tmpdir, builder) - doctreedir = os.path.join(tmpdir, 'doctree/') - - status = StringIO() - warning = StringIO() - - kwargs.update({ - 'status': status, - 'warning': warning, - }) - - confoverrides = kwargs.pop('confoverrides', {}) - confoverrides['html_theme'] = 'sphinx_rtd_theme' - extensions = confoverrides.get('extensions', []) - extensions.append('readthedocs_ext.readthedocs') - confoverrides['extensions'] = extensions - kwargs['confoverrides'] = confoverrides - - try: - app = Sphinx(srcdir, srcdir, destdir, doctreedir, builder, **kwargs) - app.builder.build_all() - yield (app, status.getvalue(), warning.getvalue()) - except Exception as e: - print('# root:', root) - print('# builder:', builder) - print('# source:', srcdir) - print('# destination:', destdir) - print('# status:', '\n' + status.getvalue()) - print('# warning:', '\n' + warning.getvalue()) - raise - finally: - shutil.rmtree(tmpdir) - - -def build_all(root, **kwargs): - for builder in ['html', 'singlehtml', 'readthedocs', 'readthedocsdirhtml', - 'readthedocssinglehtml', 'readthedocssinglehtmllocalmedia']: - with build(root, builder, **kwargs) as ret: - yield ret diff --git a/doc/substitutions.py b/doc/substitutions.py new file mode 100644 index 00000000..b5cd20bd --- /dev/null +++ b/doc/substitutions.py @@ -0,0 +1,76 @@ +""" +Substitutions for Sphinx +""" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +# pylint: disable=invalid-name + +################################# +### Standard Sphinx variables ### +################################# + +# General information about the project. +project = u'CESM Land Ice' +copyright = u'2018, Gunter Leguy, William Lipscomb, Bill Sacks' # pylint: disable=redefined-builtin +author = u'Gunter Leguy, William Lipscomb, Bill Sacks' + +# The short X.Y version. +version = u'master' + +# The full version, including alpha/beta/rc tags. +release = u'master' + +##################################################### +### Custom variables needed for doc-builder setup ### +##################################################### + +# Version label used at the top of some pages. +version_label = "the latest development code" + +####################################################### +### Custom variables optional for doc-builder setup ### +####################################################### + +tex_category = "Miscellaneous" + +# Used by HTML help builder +htmlhelp = { + "basename": "cismwrapdocdoc", # Output file base name +} + +# Used for LaTeX output +latex = { + "target_name": "cismwrapdoc.tex", + "title": "CISM Wrapper Documentation", + "documentclass": "manual", # howto, manual, or own class + "category": tex_category, +} + +# Used for man_pages and texinfo_documents +mantex = { + "name": "cismwrapdoc", + "title": "cismwrapdoc Documentation", +} + +# Used for texinfo_documents +tex = { + "dirmenu_entry": "cismwrapdoc", + "description": "One line description of project.", + "category": tex_category, +} + +############################### +### Purely custom variables ### +############################### + +nonparamfile_disclaimer_md = ( + "**Note:** The values here should be up-to-date with those used in {{version_label}}," + " but there may be mistakes." +) +nonparamfile_disclaimer_rst = ( + "**Note:** The values here should be up-to-date with those used in |version_label|," + " but there may be mistakes." +) diff --git a/doc/version_list.py b/doc/version_list.py new file mode 100644 index 00000000..20a5202c --- /dev/null +++ b/doc/version_list.py @@ -0,0 +1,36 @@ +""" +Define the versions we want to build +""" +import sys +import os +dir2add = os.path.join(os.path.dirname(__file__), "doc-builder") +if not os.path.exists(dir2add): + raise FileNotFoundError(dir2add) +sys.path.insert(0, dir2add) +# pylint: disable=wrong-import-position +from doc_builder.docs_version import DocsVersion # pylint: disable=import-error,no-name-in-module +from doc_builder.sys_utils import get_git_head_or_branch # pylint: disable=import-error,no-name-in-module + +# Branch name, tag, or commit SHA whose version of certain files we want to preserve +LATEST_REF = get_git_head_or_branch() + +# List of version definitions +VERSION_LIST = [ + DocsVersion( + short_name="latest", + display_name="Latest development code", + landing_version=True, + ref=LATEST_REF, + ), + DocsVersion( + short_name="release-cesm2.0", + display_name="CESM2.0", + ref="release-cesm2.0-build-docs", + ), + DocsVersion( + short_name="cism-release-cesm2.1", + display_name="CESM2.1", + ref="cism-release-cesm2.1-build-docs", + ), +] +# End version definitions (keep this comment; Sphinx is looking for it)