Documentation improvements (#859)

gaborbernat · web-flow · commit 88aa3052773f · 2018-06-26T15:52:56.000+01:00
- print link to where documentation is generated - 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 - add a config file for readthedocs see example output at https://tox-gaborbernat.readthedocs.io/en/doc-impr (or deep dive http://tox-gaborbernat.readthedocs.io/en/doc-impr/changelog.html)
diff --git a/.codecov.yml b/.codecov.yml
@@ -26,5 +26,4 @@ comment:
   require_changes: no
 
 ignore:
-  - "tox/_verlib.py"  # vendored in and not internally tested
-  - "tox/__main__.py"
+  - "src/tox/_verlib.py"  # vendored in and not internally tested
diff --git a/.gitignore b/.gitignore
@@ -26,3 +26,4 @@ htmlcov
 py27/
 
 .*_cache
+_draft.rst
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,7 +1,4 @@
-CHANGELOG
-=========
-
-Versions follow `Semantic Versioning <https://semver.org/>`_ (<major>.<minor>.<patch>).
+Versions follow `Semantic Versioning <https://semver.org/>`_ (``<major>.<minor>.<patch>``).
 
 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:: ../_draft.rst
+
 .. towncrier release notes start
 
 3.0.0 (2018-04-02)
@@ -92,17 +91,17 @@ Features
   ``platform.machine()``. (`#740 <https://github.com/tox-dev/tox/issues/740>`_)
 
 
-Documentation improvements
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Documentation
+^^^^^^^^^^^^^
 
 - Change favicon to the vector beach ball - by @hazalozturk
   (`#748 <https://github.com/tox-dev/tox/issues/748>`_)
 - Change sphinx theme to alabaster and add logo/favicon - by @hazalozturk
   (`#639 <https://github.com/tox-dev/tox/issues/639>`_)
 
 
-Miscellaneous / trivial changes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Miscellaneous
+^^^^^^^^^^^^^
 
 - Running ``tox`` without a ``setup.py`` now has a more friendly error message
   and gives troubleshooting suggestions - by @Volcyy.
@@ -119,8 +118,8 @@ Miscellaneous / trivial changes
 2.9.1 (2017-09-29)
 ------------------
 
-Misc
-^^^^
+Miscellaneous
+^^^^^^^^^^^^^
 
 - integrated new release process and fixed changelog rendering for pypi.org -
   by `@obestwalter <https://github.com/obestwalter>`_.
@@ -146,8 +145,8 @@ Bugfixes
   (`#571 <https://github.com/tox-dev/tox/issues/571>`_)
 
 
-Misc
-^^^^
+Miscellaneous
+^^^^^^^^^^^^^
 
 - `#635 <https://github.com/tox-dev/tox/issues/635>`_ inherit from correct exception -
   by `@obestwalter <https://github.com/obestwalter>`_
@@ -159,8 +158,8 @@ Misc
   by `@obestwalter <https://github.com/obestwalter>`_.
 
 
-Improved Documentation
-^^^^^^^^^^^^^^^^^^^^^^
+Documentation
+^^^^^^^^^^^^^
 
 - add `towncrier <https://github.com/hawkowl/towncrier>`_ to allow adding
   changelog entries with the pull requests without generating merge conflicts;
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1 +1,2 @@
-Make ``py2`` and ``py3`` aliases also resolve via ``py`` on windows
+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/859.doc.rst b/changelog/859.doc.rst
@@ -0,0 +1 @@
+Various improvements to documentation: open browser once documentation generation is done, show Github/Travis info on documentation page, remove duplicate header for changelog, generate unreleased news as DRAFT on top of changelog, make the changelog page more compact and readable (width up to 1280px) by :user:`gaborbernat`
diff --git 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
@@ -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/_static/img/tox.png b/doc/_static/img/tox.png
diff --git a/doc/_static/img/tox.svg b/doc/_static/img/tox.svg
diff --git a/doc/_static/img/toxfavi.ico b/doc/_static/img/toxfavi.ico
diff --git a/doc/_static/sphinxdoc.css b/doc/_static/sphinxdoc.css
diff --git a/doc/conf.py b/doc/conf.py
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/readthedocs.yml b/readthedocs.yml
diff --git a/setup.py b/setup.py
diff --git a/tox.ini b/tox.ini

Original file line number	Diff line number	Diff line change
`@@ -26,3 +26,4 @@ htmlcov`
`26`	`26`	`py27/`
`27`	`27`
`28`	`28`	`.*_cache`
	`29`	`+_draft.rst`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Fix bug with incorrectly defactorized dependencies - by @bartsanchez`
	`1`	+Fix bug with incorrectly defactorized dependencies (deps passed to pip were not de-factorized) - by :user:`bartsanchez`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-filter out unwanted files in package - by @obestwalter`
	`1`	+filter out unwanted files in package - by :user:`obestwalter`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-extend the plugin documentation and make lot of small fixes and improvements - by @obestwalter`
	`1`	+extend the plugin documentation and make lot of small fixes and improvements - by :user:`obestwalter`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-introduce a constants module to be used internally and as experimental API - by @obestwalter`
	`1`	+introduce a constants module to be used internally and as experimental API - by :user:`obestwalter`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-tidy up tests - remove unused fixtures, update old cinstructs, etc. - by @obestwalter`
	`1`	+tidy up tests - remove unused fixtures, update old cinstructs, etc. - by :user:`obestwalter`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-make the already existing implicit API explicit - by @obestwalter`
	`1`	+make the already existing implicit API explicit - by :user:`obestwalter`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-improve tox quickstart and corresponding tests - @obestwalter`
	`1`	+improve tox quickstart and corresponding tests - by :user:`obestwalter`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-tweak codecov settings via .codecov.yml - by @obestwalter`
	`1`	+tweak codecov settings via .codecov.yml - by :user:`obestwalter`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`		-Make ``py2`` and ``py3`` aliases also resolve via ``py`` on windows
	`1`	+Make ``py2`` and ``py3`` aliases also resolve via ``py`` on windows by :user:`asottile`. This enables the following things:
	`2`	+``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.