From 1b325d595dc99792200db0c58c58a54c37a8fa2e Mon Sep 17 00:00:00 2001 From: Bernat Gabor Date: Mon, 25 Jun 2018 12:47:27 +0100 Subject: [PATCH] Document improvements - after doc generation automatically open the generated documentation in a browser - remove old documentation css - configure alabaster to display Github stars/Travis CI, and fork me badge - allow the documentation to span up to 1280 pixels, instead of 800 (this allows many code examples to be much more readable, or changelog entries) - remove large spaces in between changelog entries for a more compact view - version strings are italic and bold for a cleaner delimitation inside the changelog - sections in a version changelog has a smaller top margin for a more compact view - automatically render news at top of the documentation under DRAFT section, this allows testing the news fragment before release - remove double header for changelog - use the :user: extlinks for changelog entries to link to contributors Github profile - improve changelog entry for issue 858 --- CHANGELOG.rst | 7 +- changelog/19.feature.rst | 2 +- changelog/477.bugfix.rst | 2 +- changelog/706.bugfix.rst | 2 +- changelog/754.misc.rst | 2 +- changelog/794.feature.rst | 2 +- changelog/797.doc.rst | 2 +- changelog/798.feature.rst | 2 +- changelog/799.doc.rst | 2 +- changelog/800.misc.rst | 2 +- changelog/801.misc.rst | 2 +- changelog/802.misc.rst | 2 +- changelog/856.feature.rst | 2 + changelog/examples.rst | 6 +- doc/_static/custom.css | 52 +++++ doc/{ => _static}/img/tox.png | Bin doc/{ => _static}/img/tox.svg | 0 doc/{ => _static}/img/toxfavi.ico | Bin doc/_static/sphinxdoc.css | 339 ------------------------------ doc/conf.py | 18 +- setup.py | 2 +- tox.ini | 8 +- 22 files changed, 93 insertions(+), 363 deletions(-) create mode 100644 changelog/856.feature.rst create mode 100644 doc/_static/custom.css rename doc/{ => _static}/img/tox.png (100%) rename doc/{ => _static}/img/tox.svg (100%) rename doc/{ => _static}/img/toxfavi.ico (100%) delete mode 100644 doc/_static/sphinxdoc.css diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 76024f6b2d..8868fdec47 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,7 +1,4 @@ -CHANGELOG -========= - -Versions follow `Semantic Versioning `_ (..). +Versions follow `Semantic Versioning `_ (``..``). Backward incompatible (breaking) changes will only be introduced in major versions with advance notice in the **Deprecations** section of releases. @@ -23,6 +20,8 @@ on Github: folder. If necessary, the generated text can be edited afterwards to e.g. merge rc changes into the final release notes. +.. include:: ../.tox/docs_out/draft_changelog.rst + .. towncrier release notes start 3.0.0 (2018-04-02) diff --git a/changelog/19.feature.rst b/changelog/19.feature.rst index 3639b28018..6ef459bc3c 100644 --- a/changelog/19.feature.rst +++ b/changelog/19.feature.rst @@ -1,3 +1,3 @@ Add support for multiple PyPy versions using default factors. This allows you to use, for example, ``pypy27`` knowing that the correct intepreter will be -used by default - by @stephenfin +used by default - by :user:`stephenfin` diff --git a/changelog/477.bugfix.rst b/changelog/477.bugfix.rst index 39e12987fa..2dc3f4fa6d 100644 --- a/changelog/477.bugfix.rst +++ b/changelog/477.bugfix.rst @@ -2,4 +2,4 @@ Add ``ignore_basepython_conflict``, which determines whether conflicting ``basepython`` settings for environments containing default factors, such as ``py27`` or ``django18-py35``, should be ignored or result in warnings. This was a common source of misconfiguration and is rarely, if ever, desirable from -a user perspective - by @stephenfin +a user perspective - by :user:`stephenfin` diff --git a/changelog/706.bugfix.rst b/changelog/706.bugfix.rst index b0827db66b..01acd68b7b 100644 --- a/changelog/706.bugfix.rst +++ b/changelog/706.bugfix.rst @@ -1 +1 @@ -Fix bug with incorrectly defactorized dependencies - by @bartsanchez +Fix bug with incorrectly defactorized dependencies (deps passed to pip were not de-factorized) - by :user:`bartsanchez` diff --git a/changelog/754.misc.rst b/changelog/754.misc.rst index 90c0d6f45c..9aeeb65623 100644 --- a/changelog/754.misc.rst +++ b/changelog/754.misc.rst @@ -1 +1 @@ -filter out unwanted files in package - by @obestwalter +filter out unwanted files in package - by :user:`obestwalter` diff --git a/changelog/794.feature.rst b/changelog/794.feature.rst index 085334b92f..046a6ae3ba 100644 --- a/changelog/794.feature.rst +++ b/changelog/794.feature.rst @@ -2,4 +2,4 @@ Add support to explicitly invoke interpreter directives for environments with long path lengths. In the event that ``tox`` cannot invoke scripts with a system-limited shebang (e.x. a Linux host running a Jenkins Pipeline), a user can set the environment variable ``TOX_LIMITED_SHEBANG`` to workaround the -system's limitation (e.x. ``export TOX_LIMITED_SHEBANG=1``) - by @jdknight +system's limitation (e.x. ``export TOX_LIMITED_SHEBANG=1``) - by :user:`jdknight` diff --git a/changelog/797.doc.rst b/changelog/797.doc.rst index ad4d96935a..6464c9c2e9 100644 --- a/changelog/797.doc.rst +++ b/changelog/797.doc.rst @@ -1 +1 @@ -extend the plugin documentation and make lot of small fixes and improvements - by @obestwalter +extend the plugin documentation and make lot of small fixes and improvements - by :user:`obestwalter` diff --git a/changelog/798.feature.rst b/changelog/798.feature.rst index 87caabf303..25eba60e26 100644 --- a/changelog/798.feature.rst +++ b/changelog/798.feature.rst @@ -1 +1 @@ -introduce a constants module to be used internally and as experimental API - by @obestwalter +introduce a constants module to be used internally and as experimental API - by :user:`obestwalter` diff --git a/changelog/799.doc.rst b/changelog/799.doc.rst index c3031d682b..ba23f96dfe 100644 --- a/changelog/799.doc.rst +++ b/changelog/799.doc.rst @@ -1 +1 @@ -tidy up tests - remove unused fixtures, update old cinstructs, etc. - by @obestwalter +tidy up tests - remove unused fixtures, update old cinstructs, etc. - by :user:`obestwalter` diff --git a/changelog/800.misc.rst b/changelog/800.misc.rst index 6fddb9740f..c614256c72 100644 --- a/changelog/800.misc.rst +++ b/changelog/800.misc.rst @@ -1 +1 @@ -make the already existing implicit API explicit - by @obestwalter +make the already existing implicit API explicit - by :user:`obestwalter` diff --git a/changelog/801.misc.rst b/changelog/801.misc.rst index 8f148d6767..1584748783 100644 --- a/changelog/801.misc.rst +++ b/changelog/801.misc.rst @@ -1 +1 @@ -improve tox quickstart and corresponding tests - @obestwalter +improve tox quickstart and corresponding tests - by :user:`obestwalter` diff --git a/changelog/802.misc.rst b/changelog/802.misc.rst index facd8bb2bb..85dfebb264 100644 --- a/changelog/802.misc.rst +++ b/changelog/802.misc.rst @@ -1 +1 @@ -tweak codecov settings via .codecov.yml - by @obestwalter +tweak codecov settings via .codecov.yml - by :user:`obestwalter` diff --git a/changelog/856.feature.rst b/changelog/856.feature.rst new file mode 100644 index 0000000000..e6776c68f7 --- /dev/null +++ b/changelog/856.feature.rst @@ -0,0 +1,2 @@ +Make ``py2`` and ``py3`` aliases also resolve via ``py`` on windows by :user:`asottile`. This enables the following things: +``tox -e py2`` and ``tox -e py3`` work on windows (they already work on posix); and setting ``basepython=python2`` or ``basepython=python3`` now works on windows. diff --git a/changelog/examples.rst b/changelog/examples.rst index 746d86de11..a1c1204706 100644 --- a/changelog/examples.rst +++ b/changelog/examples.rst @@ -2,17 +2,17 @@ file ``544.doc.rst``:: - explain everything much better - by @passionate_technicalwriter + explain everything much better - by :user:`passionate_technicalwriter` file ``544.feature.rst``:: - ``tox --version`` now shows information about all registered plugins - by @obestwalter + ``tox --version`` now shows information about all registered plugins - by :user:`obestwalter` file ``571.bugfix.rst``:: ``skip_install`` overrides ``usedevelop`` (``usedevelop`` is an option to choose the installation type if the package is installed and `skip_install` determines if it should be - installed at all) - by @ferdonline + installed at all) - by :user:`ferdonline` .. see tox/pyproject.toml for all available categories diff --git a/doc/_static/custom.css b/doc/_static/custom.css new file mode 100644 index 0000000000..5244875941 --- /dev/null +++ b/doc/_static/custom.css @@ -0,0 +1,52 @@ +div.document { + width: 100%; + max-width: 1520px; +} + +div.body { + max-width: 1280px; +} + +img, div.figure { + margin: 0 !important +} + +ul > li { + text-align: justify; +} + +ul > li > p { + margin-bottom: 0; + +} + +div.body code.descclassname { + display: none +} + +.wy-table-responsive table td { + white-space: normal !important; +} + +.wy-table-responsive { + overflow: visible !important; +} + +div.toctree-wrapper.compound > ul > li { + margin: 0; + padding: 0 +} + +code.docutils.literal { + background-color: #ECF0F3; + padding: 0 1px; +} + +div#changelog-history h3{ + margin-top: 10px; +} + +div#changelog-history h2{ + font-style: italic; + font-weight: bold; +} diff --git a/doc/img/tox.png b/doc/_static/img/tox.png similarity index 100% rename from doc/img/tox.png rename to doc/_static/img/tox.png diff --git a/doc/img/tox.svg b/doc/_static/img/tox.svg similarity index 100% rename from doc/img/tox.svg rename to doc/_static/img/tox.svg diff --git a/doc/img/toxfavi.ico b/doc/_static/img/toxfavi.ico similarity index 100% rename from doc/img/toxfavi.ico rename to doc/_static/img/toxfavi.ico diff --git a/doc/_static/sphinxdoc.css b/doc/_static/sphinxdoc.css deleted file mode 100644 index 78de68eaa4..0000000000 --- a/doc/_static/sphinxdoc.css +++ /dev/null @@ -1,339 +0,0 @@ -/* - * sphinxdoc.css_t - * ~~~~~~~~~~~~~~~ - * - * Sphinx stylesheet -- sphinxdoc theme. Originally created by - * Armin Ronacher for Werkzeug. - * - * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', - 'Verdana', sans-serif; - font-size: 1.1em; - letter-spacing: -0.01em; - line-height: 150%; - text-align: center; - background-color: #BFD1D4; - color: black; - padding: 0; - border: 1px solid #aaa; - - margin: 0px 80px 0px 80px; - min-width: 740px; -} - -div.document { - background-color: white; - text-align: left; - background-image: url(contents.png); - background-repeat: repeat-x; -} - -div.bodywrapper { - margin: 0 240px 0 0; - border-right: 1px solid #ccc; -} - -div.body { - margin: 0; - padding: 0.5em 20px 20px 20px; -} - -div.related { - font-size: 0.8em; -} - -div.related ul { - background-image: url(navigation.png); - height: 2em; - border-top: 1px solid #ddd; - border-bottom: 1px solid #ddd; -} - -div.related ul li { - margin: 0; - padding: 0; - height: 2em; - float: left; -} - -div.related ul li.right { - float: right; - margin-right: 5px; -} - -div.related ul li a { - margin: 0; - padding: 0 5px 0 5px; - line-height: 1.75em; - color: #EE9816; -} - -div.related ul li a:hover { - color: #3CA8E7; -} - -div.sphinxsidebarwrapper { - padding: 0; -} - -div.sphinxsidebar { - margin: 0; - padding: 0.5em 15px 15px 0; - width: 210px; - float: right; - font-size: 1em; - text-align: left; -} - -div.sphinxsidebar h3, div.sphinxsidebar h4 { - margin: 1em 0 0.5em 0; - font-size: 1em; - padding: 0.1em 0 0.1em 0.5em; - color: white; - border: 1px solid #86989B; - background-color: #AFC1C4; -} - -div.sphinxsidebar h3 a { - color: white; -} - -div.sphinxsidebar ul { - padding-left: 1.5em; - margin-top: 7px; - padding: 0; - line-height: 130%; -} - -div.sphinxsidebar ul ul { - margin-left: 20px; -} - -div.footer { - background-color: #E3EFF1; - color: #86989B; - padding: 3px 8px 3px 0; - clear: both; - font-size: 0.8em; - text-align: right; -} - -div.footer a { - color: #86989B; - text-decoration: underline; -} - -/* -- body styles ----------------------------------------------------------- */ - -p { - margin: 0.8em 0 0.5em 0; -} - -a { - color: #CA7900; - text-decoration: none; -} - -a:hover { - color: #2491CF; -} - -div.body a { - text-decoration: underline; -} - -h1 { - margin: 0; - padding: 0.7em 0 0.3em 0; - font-size: 1.5em; - color: #11557C; -} - -h2 { - margin: 1.3em 0 0.2em 0; - font-size: 1.35em; - padding: 0; -} - -h3 { - margin: 1em 0 -0.3em 0; - font-size: 1.2em; -} - -div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { - color: black!important; -} - -h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { - display: none; - margin: 0 0 0 0.3em; - padding: 0 0.2em 0 0.2em; - color: #aaa!important; -} - -h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, -h5:hover a.anchor, h6:hover a.anchor { - display: inline; -} - -h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, -h5 a.anchor:hover, h6 a.anchor:hover { - color: #777; - background-color: #eee; -} - -a.headerlink { - color: #c60f0f!important; - font-size: 1em; - margin-left: 6px; - padding: 0 4px 0 4px; - text-decoration: none!important; -} - -a.headerlink:hover { - background-color: #ccc; - color: white!important; -} - -cite, code, tt { - font-family: 'Consolas', 'Deja Vu Sans Mono', - 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.01em; -} - -tt { - background-color: #f2f2f2; - border-bottom: 1px solid #ddd; - color: #333; -} - -tt.descname, tt.descclassname, tt.xref { - border: 0; -} - -hr { - border: 1px solid #abc; - margin: 2em; -} - -a tt { - border: 0; - color: #CA7900; -} - -a tt:hover { - color: #2491CF; -} - -pre { - font-family: 'Consolas', 'Deja Vu Sans Mono', - 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.015em; - line-height: 120%; - padding: 0.5em; - border: 1px solid #ccc; - background-color: #f8f8f8; -} - -pre a { - color: inherit; - text-decoration: underline; -} - -td.linenos pre { - padding: 0.5em 0; -} - -div.quotebar { - background-color: #f8f8f8; - max-width: 350px; - float: right; - padding: 2px 7px; - border: 1px solid #ccc; -} - -div.topic { - background-color: #f8f8f8; -} - -table { - border-collapse: collapse; - margin: 0 -0.5em 0 -0.5em; -} - -table td, table th { - padding: 0.2em 0.5em 0.2em 0.5em; -} - -div.admonition, div.warning { - font-size: 0.9em; - margin: 1em 0 1em 0; - border: 1px solid #86989B; - background-color: #f7f7f7; - padding: 0; -} - -div.admonition p, div.warning p { - margin: 0.5em 1em 0.5em 1em; - padding: 0; -} - -div.admonition pre, div.warning pre { - margin: 0.4em 1em 0.4em 1em; -} - -div.admonition p.admonition-title, -div.warning p.admonition-title { - margin: 0; - padding: 0.1em 0 0.1em 0.5em; - color: white; - border-bottom: 1px solid #86989B; - font-weight: bold; - background-color: #AFC1C4; -} - -div.warning { - border: 1px solid #940000; -} - -div.warning p.admonition-title { - background-color: #CF0000; - border-bottom-color: #940000; -} - -div.admonition ul, div.admonition ol, -div.warning ul, div.warning ol { - margin: 0.1em 0.5em 0.5em 3em; - padding: 0; -} - -div.versioninfo { - margin: 1em 0 0 0; - border: 1px solid #ccc; - background-color: #DDEAF0; - padding: 8px; - line-height: 1.3em; - font-size: 0.9em; -} - -.viewcode-back { - font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', - 'Verdana', sans-serif; -} - -div.viewcode-block:target { - background-color: #f4debf; - border-top: 1px solid #ac9; - border-bottom: 1px solid #ac9; -} diff --git a/doc/conf.py b/doc/conf.py index 07924c374e..a291a42356 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -28,11 +28,23 @@ templates_path = ["_templates"] pygments_style = "sphinx" + html_theme = "alabaster" -html_logo = "img/tox.png" -html_favicon = "img/toxfavi.ico" -html_static_path = ["_static"] +html_theme_options = { + "logo": "img/tox.png", + "github_user": "tox-dev", + "github_repo": "tox", + "description": "standardise testing in Python", + "github_banner": "true", + "travis_button": "true", + "badge_branch": "master", + "fixed_sidebar": "false", +} +html_sidebars = { + "**": ["about.html", "localtoc.html", "relations.html", "searchbox.html", "donate.html"] +} html_show_sourcelink = False +html_static_path = ["_static"] htmlhelp_basename = "{}doc".format(project) latex_documents = [("index", "tox.tex", u"{} Documentation".format(project), author, "manual")] man_pages = [("index", project, u"{} Documentation".format(project), [author], 1)] diff --git a/setup.py b/setup.py index 9a30a85ac0..eb81e8dec2 100644 --- a/setup.py +++ b/setup.py @@ -59,7 +59,7 @@ def main(): "pytest-timeout", "pytest-xdist", ], - "docs": ["sphinx >= 1.6.3, < 2", "towncrier >= 17.8.0"], + "docs": ["sphinx >= 1.7.5, < 2", "towncrier >= 18.5.0"], "publish": ["devpi", "twine"], }, classifiers=[ diff --git a/tox.ini b/tox.ini index d60dded45b..21f594f4aa 100644 --- a/tox.ini +++ b/tox.ini @@ -22,11 +22,15 @@ commands = pytest {posargs:--cov="{envsitepackagesdir}/tox" --cov-config="{toxin [testenv:docs] description = invoke sphinx-build to build the HTML docs and check that all links are valid -whitelist_externals = sphinx-build +whitelist_externals = sphinx-build git +passenv = * basepython = python3.6 extras = docs changedir = {toxinidir} -commands = sphinx-build -d "{toxworkdir}/docs_doctree" doc "{toxworkdir}/docs_out" --color -W -bhtml {posargs} +commands = python tasks/pre-process-changelog.py + python -c 'import subprocess; from pathlib import Path; Path("{toxworkdir}/docs_out/draft_changelog.rst").write_bytes(subprocess.check_output(["towncrier", "--draft", "--version", "DRAFT"]))' + sphinx-build -d "{toxworkdir}/docs_doctree" doc "{toxworkdir}/docs_out" --color -W -bhtml {posargs} + python -m webbrowser -t "{toxworkdir}/docs_out/index.html" [testenv:fix-lint] description = format the code base to adhere to our styles, and complain about what we cannot do automatically