Documentation improvements #859
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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
Codecov Report
@@ Coverage Diff @@
## master #859 +/- ##
=====================================
+ Coverage 92% 93% +1%
=====================================
Files 13 12 -1
Lines 2421 2326 -95
Branches 430 408 -22
=====================================
- Hits 2224 2153 -71
+ Misses 123 107 -16
+ Partials 74 66 -8 |
gaborbernat
requested review from
obestwalter and
asottile
and removed request for
obestwalter
gaborbernat
added
feature:new
sfdye
referenced
this pull request
in cookiecutter/cookiecutter-django
Jul 10, 2018
This PR updates [tox](https://pypi.org/project/tox) from **3.0.0** to **3.1.1**. <details> <summary>Changelog</summary> ### 3.1.0 ``` ------------------ Bugfixes ^^^^^^^^ - 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 :user:`stephenfin` (`477 <https://github.com/tox-dev/tox/issues/477>`_) - Fix bug with incorrectly defactorized dependencies (deps passed to pip were not de-factorized) - by :user:`bartsanchez` (`706 <https://github.com/tox-dev/tox/issues/706>`_) Features ^^^^^^^^ - 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 :user:`stephenfin` (`19 <https://github.com/tox-dev/tox/issues/19>`_) - 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 :user:`jdknight` (`794 <https://github.com/tox-dev/tox/issues/794>`_) - introduce a constants module to be used internally and as experimental API - by :user:`obestwalter` (`798 <https://github.com/tox-dev/tox/issues/798>`_) - 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. (`856 <https://github.com/tox-dev/tox/issues/856>`_) - Replace the internal version parsing logic from the not well tested `PEP-386 <https://www.python.org/dev/peps/pep-0386/>`_ parser for the more general `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_. `packaging >= 17.1 <https://pypi.org/project/packaging/>`_ is now an install dependency by :user:`gaborbernat`. (`860 <https://github.com/tox-dev/tox/issues/860>`_) Documentation ^^^^^^^^^^^^^ - extend the plugin documentation and make lot of small fixes and improvements - by :user:`obestwalter` (`797 <https://github.com/tox-dev/tox/issues/797>`_) - tidy up tests - remove unused fixtures, update old cinstructs, etc. - by :user:`obestwalter` (`799 <https://github.com/tox-dev/tox/issues/799>`_) - 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` (`859 <https://github.com/tox-dev/tox/issues/859>`_) Miscellaneous ^^^^^^^^^^^^^ - filter out unwanted files in package - by :user:`obestwalter` (`754 <https://github.com/tox-dev/tox/issues/754>`_) - make the already existing implicit API explicit - by :user:`obestwalter` (`800 <https://github.com/tox-dev/tox/issues/800>`_) - improve tox quickstart and corresponding tests - by :user:`obestwalter` (`801 <https://github.com/tox-dev/tox/issues/801>`_) - tweak codecov settings via .codecov.yml - by :user:`obestwalter` (`802 <https://github.com/tox-dev/tox/issues/802>`_) ``` </details> <details> <summary>Links</summary> - PyPI: https://pypi.org/project/tox - Changelog: https://pyup.io/changelogs/tox/ - Docs: https://tox.readthedocs.org/ </details>
sloria
referenced
this pull request
in sloria/doitlive
Jul 15, 2018
This PR updates [tox](https://pypi.org/project/tox) from **3.0.0** to **3.1.2**. <details> <summary>Changelog</summary> ### 3.1.1 ``` ------------------ Bugfixes ^^^^^^^^ - PyPi documentation for ``3.1.0`` is broken. Added test to check for this, and fix it by :user:`gaborbernat`. (`879 <https://github.com/tox-dev/tox/issues/879>`_) ``` ### 3.1.0 ``` ------------------ Bugfixes ^^^^^^^^ - 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 :user:`stephenfin` (`477 <https://github.com/tox-dev/tox/issues/477>`_) - Fix bug with incorrectly defactorized dependencies (deps passed to pip were not de-factorized) - by :user:`bartsanchez` (`706 <https://github.com/tox-dev/tox/issues/706>`_) Features ^^^^^^^^ - 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 :user:`stephenfin` (`19 <https://github.com/tox-dev/tox/issues/19>`_) - 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 :user:`jdknight` (`794 <https://github.com/tox-dev/tox/issues/794>`_) - introduce a constants module to be used internally and as experimental API - by :user:`obestwalter` (`798 <https://github.com/tox-dev/tox/issues/798>`_) - 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. (`856 <https://github.com/tox-dev/tox/issues/856>`_) - Replace the internal version parsing logic from the not well tested `PEP-386 <https://www.python.org/dev/peps/pep-0386/>`_ parser for the more general `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_. `packaging >= 17.1 <https://pypi.org/project/packaging/>`_ is now an install dependency by :user:`gaborbernat`. (`860 <https://github.com/tox-dev/tox/issues/860>`_) Documentation ^^^^^^^^^^^^^ - extend the plugin documentation and make lot of small fixes and improvements - by :user:`obestwalter` (`797 <https://github.com/tox-dev/tox/issues/797>`_) - tidy up tests - remove unused fixtures, update old cinstructs, etc. - by :user:`obestwalter` (`799 <https://github.com/tox-dev/tox/issues/799>`_) - 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` (`859 <https://github.com/tox-dev/tox/issues/859>`_) Miscellaneous ^^^^^^^^^^^^^ - filter out unwanted files in package - by :user:`obestwalter` (`754 <https://github.com/tox-dev/tox/issues/754>`_) - make the already existing implicit API explicit - by :user:`obestwalter` (`800 <https://github.com/tox-dev/tox/issues/800>`_) - improve tox quickstart and corresponding tests - by :user:`obestwalter` (`801 <https://github.com/tox-dev/tox/issues/801>`_) - tweak codecov settings via .codecov.yml - by :user:`obestwalter` (`802 <https://github.com/tox-dev/tox/issues/802>`_) ``` </details> <details> <summary>Links</summary> - PyPI: https://pypi.org/project/tox - Changelog: https://pyup.io/changelogs/tox/ - Docs: https://tox.readthedocs.org/ </details>
DmytroLitvinov
referenced
this pull request
in DmytroLitvinov/kuna
Aug 6, 2018
### Update [pip](https://pypi.org/project/pip) from **10.0.1** to **18.0**. <details> <summary>Changelog</summary> ### 18.0 ``` ================= Process ------- - Switch to a Calendar based versioning scheme. - Formally document our deprecation process as a minimum of 6 months of deprecation warnings. - Adopt and document NEWS fragment writing style. - Switch to releasing a new, non bug fix version of pip every 3 months. Deprecations and Removals ------------------------- - Remove the legacy format from pip list. (3651, 3654) - Dropped support for Python 3.3. (3796) - Remove support for cleaning up egg fragment postfixes. (4174) - Remove the shim for the old get-pip.py location. (5520) For the past 2 years, it's only been redirecting users to use the newer https://bootstrap.pypa.io/get-pip.py location. Features -------- - Introduce a new --prefer-binary flag, to prefer older wheels over newer source packages. (3785) - Improve autocompletion function on file name completion after options which have ``<file>``, ``<dir>`` or ``<path>`` as metavar. (4842, 5125) - Add support for installing PEP 518 build dependencies from source. (5229) - Improve status message when upgrade is skipped due to only-if-needed strategy. (5319) Bug Fixes --------- - Update pip's self-check logic to not use a virtualenv specific file and honor cache-dir. (3905) - Remove compiled pyo files for wheel packages. (4471) - Speed up printing of newly installed package versions. (5127) - Restrict install time dependency warnings to directly-dependant packages. (5196, 5457) Warning about the entire package set has resulted in users getting confused as to why pip is printing these warnings. - Improve handling of PEP 518 build requirements: support environment markers and extras. (5230, 5265) - Remove username/password from log message when using index with basic auth. (5249) - Remove trailing os.sep from PATH directories to avoid false negatives. (5293) - Fix "pip wheel pip" being blocked by the "don't use pip to modify itself" check. (5311, 5312) - Disable pip's version check (and upgrade message) when installed by a different package manager. (5346) This works better with Linux distributions where pip's upgrade message may result in users running pip in a manner that modifies files that should be managed by the OS's package manager. - Check for file existence and unlink first when clobbering existing files during a wheel install. (5366) - Improve error message to be more specific when no files are found as listed in as listed in PKG-INFO. (5381) - Always read ``pyproject.toml`` as UTF-8. This fixes Unicode handling on Windows and Python 2. (5482) - Fix a crash that occurs when PATH not set, while generating script location warning. (5558) - Disallow packages with ``pyproject.toml`` files that have an empty build-system table. (5627) Vendored Libraries ------------------ - Update CacheControl to 0.12.5. - Update certifi to 2018.4.16. - Update distro to 1.3.0. - Update idna to 2.7. - Update ipaddress to 1.0.22. - Update pkg_resources to 39.2.0 (via setuptools). - Update progress to 1.4. - Update pytoml to 0.1.16. - Update requests to 2.19.1. - Update urllib3 to 1.23. Improved Documentation ---------------------- - Document how to use pip with a proxy server. (512, 5574) - Document that the output of pip show is in RFC-compliant mail header format. (5261) ``` </details> <details> <summary>Links</summary> - PyPI: https://pypi.org/project/pip - Changelog: https://pyup.io/changelogs/pip/ - Homepage: https://pip.pypa.io/ </details> ### Update [tox](https://pypi.org/project/tox) from **3.0.0** to **3.1.3**. <details> <summary>Changelog</summary> ### 3.1.2 ``` ------------------ Bugfixes ^^^^^^^^ - Revert "Fix bug with incorrectly defactorized dependencies (`772 <https://github.com/tox-dev/tox/issues/772>`_)" due to a regression (`(799) <https://github.com/tox-dev/tox/issues/899>`_) - by :user:`obestwalter` ``` ### 3.1.1 ``` ------------------ Bugfixes ^^^^^^^^ - PyPi documentation for ``3.1.0`` is broken. Added test to check for this, and fix it by :user:`gaborbernat`. (`879 <https://github.com/tox-dev/tox/issues/879>`_) ``` ### 3.1.0 ``` ------------------ Bugfixes ^^^^^^^^ - 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 :user:`stephenfin` (`477 <https://github.com/tox-dev/tox/issues/477>`_) - Fix bug with incorrectly defactorized dependencies (deps passed to pip were not de-factorized) - by :user:`bartsanchez` (`706 <https://github.com/tox-dev/tox/issues/706>`_) Features ^^^^^^^^ - 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 :user:`stephenfin` (`19 <https://github.com/tox-dev/tox/issues/19>`_) - 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 :user:`jdknight` (`794 <https://github.com/tox-dev/tox/issues/794>`_) - introduce a constants module to be used internally and as experimental API - by :user:`obestwalter` (`798 <https://github.com/tox-dev/tox/issues/798>`_) - 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. (`856 <https://github.com/tox-dev/tox/issues/856>`_) - Replace the internal version parsing logic from the not well tested `PEP-386 <https://www.python.org/dev/peps/pep-0386/>`_ parser for the more general `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_. `packaging >= 17.1 <https://pypi.org/project/packaging/>`_ is now an install dependency by :user:`gaborbernat`. (`860 <https://github.com/tox-dev/tox/issues/860>`_) Documentation ^^^^^^^^^^^^^ - extend the plugin documentation and make lot of small fixes and improvements - by :user:`obestwalter` (`797 <https://github.com/tox-dev/tox/issues/797>`_) - tidy up tests - remove unused fixtures, update old cinstructs, etc. - by :user:`obestwalter` (`799 <https://github.com/tox-dev/tox/issues/799>`_) - 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` (`859 <https://github.com/tox-dev/tox/issues/859>`_) Miscellaneous ^^^^^^^^^^^^^ - filter out unwanted files in package - by :user:`obestwalter` (`754 <https://github.com/tox-dev/tox/issues/754>`_) - make the already existing implicit API explicit - by :user:`obestwalter` (`800 <https://github.com/tox-dev/tox/issues/800>`_) - improve tox quickstart and corresponding tests - by :user:`obestwalter` (`801 <https://github.com/tox-dev/tox/issues/801>`_) - tweak codecov settings via .codecov.yml - by :user:`obestwalter` (`802 <https://github.com/tox-dev/tox/issues/802>`_) ``` </details> <details> <summary>Links</summary> - PyPI: https://pypi.org/project/tox - Changelog: https://pyup.io/changelogs/tox/ - Docs: https://tox.readthedocs.org/ </details> ### Update [Sphinx](https://pypi.org/project/Sphinx) from **1.7.5** to **1.7.6**. <details> <summary>Changelog</summary> ### 1.7.6 ``` ============================== Dependencies ------------ Incompatible changes -------------------- Deprecated ---------- Features added -------------- Bugs fixed ---------- * 5037: LaTeX ``\sphinxupquote{}`` breaks in Russian * sphinx.testing uses deprecated pytest API; ``Node.get_marker(name)`` * 5016: crashed when recommonmark.AutoStrictify is enabled * 5022: latex: crashed with docutils package provided by Debian/Ubuntu * 5009: latex: a label for table is vanished if table does not have a caption * 5048: crashed with numbered toctree * 2410: C, render empty argument lists for macros. * C++, fix lookup of full template specializations with no template arguments. * 4667: C++, fix assertion on missing references in global scope when using intersphinx. Thanks to Alan M. Carroll. * 5019: autodoc: crashed by Form Feed Character * 5032: autodoc: loses the first staticmethod parameter for old styled classes * 5036: quickstart: Typing Ctrl-U clears the whole of line * 5066: html: "relations" sidebar is not shown by default * 5091: latex: curly braces in index entries are not handled correctly * 5070: epub: Wrong internal href fragment links * 5104: apidoc: Interface of ``sphinx.apidoc:main()`` has changed * 5076: napoleon raises RuntimeError with python 3.7 * 5125: sphinx-build: Interface of ``sphinx:main()`` has changed * sphinx-build: ``sphinx.cmd.build.main()`` refers ``sys.argv`` instead of given argument * 5146: autosummary: warning is emitted when the first line of docstring ends with literal notation * autosummary: warnings of autosummary indicates wrong location (refs: 5146) * 5143: autodoc: crashed on inspecting dict like object which does not support sorting Testing -------- ``` </details> <details> <summary>Links</summary> - PyPI: https://pypi.org/project/sphinx - Changelog: https://pyup.io/changelogs/sphinx/ - Homepage: http://sphinx-doc.org/ </details> ### Update [cryptography](https://pypi.org/project/cryptography) from **2.2.2** to **2.3**. <details> <summary>Changelog</summary> ### 2.3 ``` ~~~~~~~~~~~~~~~~ * **SECURITY ISSUE:** :meth:`~cryptography.hazmat.primitives.ciphers.AEADDecryptionContext.finalize_with_tag` allowed tag truncation by default which can allow tag forgery in some cases. The method now enforces the ``min_tag_length`` provided to the :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` constructor. *CVE-2018-10903* * Added support for Python 3.7. * Added :meth:`~cryptography.fernet.Fernet.extract_timestamp` to get the authenticated timestamp of a :doc:`Fernet </fernet>` token. * Support for Python 2.7.x without ``hmac.compare_digest`` has been deprecated. We will require Python 2.7.7 or higher (or 2.7.6 on Ubuntu) in the next ``cryptography`` release. * Fixed multiple issues preventing ``cryptography`` from compiling against LibreSSL 2.7.x. * Added :class:`~cryptography.x509.CertificateRevocationList.get_revoked_certificate_by_serial_number` for quick serial number searches in CRLs. * The :class:`~cryptography.x509.RelativeDistinguishedName` class now preserves the order of attributes. Duplicate attributes now raise an error instead of silently discarding duplicates. * :func:`~cryptography.hazmat.primitives.keywrap.aes_key_unwrap` and :func:`~cryptography.hazmat.primitives.keywrap.aes_key_unwrap_with_padding` now raise :class:`~cryptography.hazmat.primitives.keywrap.InvalidUnwrap` if the wrapped key is an invalid length, instead of ``ValueError``. .. _v2-2-2: ``` </details> <details> <summary>Links</summary> - PyPI: https://pypi.org/project/cryptography - Changelog: https://pyup.io/changelogs/cryptography/ - Repo: https://github.com/pyca/cryptography </details> ### Update [PyYAML](https://pypi.org/project/PyYAML) from **3.12** to **3.13**. *The bot wasn't able to find a changelog for this release. [Got an idea?](https://github.com/pyupio/changelogs/issues/new)* <details> <summary>Links</summary> - PyPI: https://pypi.org/project/pyyaml - Homepage: http://pyyaml.org/wiki/PyYAML </details>
webknjaz
added a commit
to ansible/pylibssh
that referenced
this pull request
Jul 31, 2020
This change implements injecting the Towncrier draft change notes RST output into the Sphinx-managed docs site. It is heavily inspired by the work of @gaborbernat in tox and reinvented as a native Sphinx extension. Ref: tox-dev/tox#859 In internally generates an unreleased changelog for the next unpublished project version (by calling `towncrier` in a subprocess) and provides it for injection as an RST directive called "towncrier-draft-entries". To start using it, first, add it to extensions in `conf.py`: extensions.append(towncrier_draft_ext) Then, optionally, set the global extensions options: towncrier_draft_autoversion_mode = 'scm-draft' # or: 'scm', 'draft', 'sphinx-version', 'sphinx-release' towncrier_draft_include_empty = True towncrier_draft_working_directory = PROJECT_ROOT_DIR towncrier_draft_config_path = 'pyproject.toml' # relative to cwd Their meaning is as follows: * towncrier_draft_autoversion_mode -- mechanism for the fallback version detection. It kicks in if, when using the directive, you don't specify the version argument and then will be passed to the `towncrier` invocation. Possible values are: * 'scm-draft' -- default, use setuptools-scm followed by a string "[UNRELEASED DRAFT]" * 'scm' -- use setuptools-scm * 'draft' -- use just a string "[UNRELEASED DRAFT]" * 'sphinx-version' -- use value of the "version" var in as set in `conf.py` * 'sphinx-release' -- use value of the "release" var in as set in `conf.py` * towncrier_draft_include_empty -- control whether the directive injects anything if there's no fragments in the repo. Boolean, defaults to `True`. * towncrier_draft_working_directory -- if set, this will be the current working directory of the `towncrier` invocation. * towncrier_draft_config_path -- path of the custom config to use for the invocation. Should be relative to the working directory. Not yet supported: the corresponding Towncrier CLI option is in their master but is not yet released. Don't use it unless you install a bleading-edge towncrier copy (or they make a release). Finally, use the directive in your RST source as follows: .. towncrier-draft-entries:: |release| [UNRELEASED DRAFT] The inline argument of the directive is what is passed to towncrier as a target version. It is optional and if not set, the fallback from the global config will be used. Pro tip: you can use RST substitutions like `|release|` or `|version|` in order to match the version with what's set in Sphinx and other release-related configs.
webknjaz
added a commit
to ansible/pylibssh
that referenced
this pull request
Jul 31, 2020
This change implements injecting the Towncrier draft change notes RST output into the Sphinx-managed docs site. It is heavily inspired by the work of @gaborbernat in tox and reinvented as a native Sphinx extension. Ref: tox-dev/tox#859 In internally generates an unreleased changelog for the next unpublished project version (by calling `towncrier` in a subprocess) and provides it for injection as an RST directive called "towncrier-draft-entries". To start using it, first, add it to extensions in `conf.py`: extensions.append(towncrier_draft_ext) Then, optionally, set the global extensions options: towncrier_draft_autoversion_mode = 'scm-draft' # or: 'scm', 'draft', 'sphinx-version', 'sphinx-release' towncrier_draft_include_empty = True towncrier_draft_working_directory = PROJECT_ROOT_DIR towncrier_draft_config_path = 'pyproject.toml' # relative to cwd Their meaning is as follows: * towncrier_draft_autoversion_mode -- mechanism for the fallback version detection. It kicks in if, when using the directive, you don't specify the version argument and then will be passed to the `towncrier` invocation. Possible values are: * 'scm-draft' -- default, use setuptools-scm followed by a string "[UNRELEASED DRAFT]" * 'scm' -- use setuptools-scm * 'draft' -- use just a string "[UNRELEASED DRAFT]" * 'sphinx-version' -- use value of the "version" var in as set in `conf.py` * 'sphinx-release' -- use value of the "release" var in as set in `conf.py` * towncrier_draft_include_empty -- control whether the directive injects anything if there's no fragments in the repo. Boolean, defaults to `True`. * towncrier_draft_working_directory -- if set, this will be the current working directory of the `towncrier` invocation. * towncrier_draft_config_path -- path of the custom config to use for the invocation. Should be relative to the working directory. Not yet supported: the corresponding Towncrier CLI option is in their master but is not yet released. Don't use it unless you install a bleading-edge towncrier copy (or they make a release). Finally, use the directive in your RST source as follows: .. towncrier-draft-entries:: |release| [UNRELEASED DRAFT] The inline argument of the directive is what is passed to towncrier as a target version. It is optional and if not set, the fallback from the global config will be used. Pro tip: you can use RST substitutions like `|release|` or `|version|` in order to match the version with what's set in Sphinx and other release-related configs.
webknjaz
added a commit
to webknjaz/tox
that referenced
this pull request
Jul 31, 2020
This change implements injecting the Towncrier draft change notes RST output into the Sphinx-managed docs site. It is heavily inspired by the work of @gaborbernat in tox and reinvented as a native Sphinx extension. Refs: * tox-dev#859 * ansible/pylibssh@f5f9ef1 In internally generates an unreleased changelog for the next unpublished project version (by calling `towncrier` in a subprocess) and provides it for injection as an RST directive called "towncrier-draft-entries". To start using it, first, add it to extensions in `conf.py`: extensions.append('towncrier_draft_ext') Then, optionally, set the global extensions options: towncrier_draft_autoversion_mode = 'scm-draft' # or: 'scm', 'draft', 'sphinx-version', 'sphinx-release' towncrier_draft_include_empty = True towncrier_draft_working_directory = PROJECT_ROOT_DIR towncrier_draft_config_path = 'pyproject.toml' # relative to cwd Their meaning is as follows: * towncrier_draft_autoversion_mode -- mechanism for the fallback version detection. It kicks in if, when using the directive, you don't specify the version argument and then will be passed to the `towncrier` invocation. Possible values are: * 'scm-draft' -- default, use setuptools-scm followed by a string "[UNRELEASED DRAFT]" * 'scm' -- use setuptools-scm * 'draft' -- use just a string "[UNRELEASED DRAFT]" * 'sphinx-version' -- use value of the "version" var in as set in `conf.py` * 'sphinx-release' -- use value of the "release" var in as set in `conf.py` * towncrier_draft_include_empty -- control whether the directive injects anything if there's no fragments in the repo. Boolean, defaults to `True`. * towncrier_draft_working_directory -- if set, this will be the current working directory of the `towncrier` invocation. * towncrier_draft_config_path -- path of the custom config to use for the invocation. Should be relative to the working directory. Not yet supported: the corresponding Towncrier CLI option is in their master but is not yet released. Don't use it unless you install a bleading-edge towncrier copy (or they make a release). Finally, use the directive in your RST source as follows: .. towncrier-draft-entries:: |release| [UNRELEASED DRAFT] The inline argument of the directive is what is passed to towncrier as a target version. It is optional and if not set, the fallback from the global config will be used. Pro tip: you can use RST substitutions like `|release|` or `|version|` in order to match the version with what's set in Sphinx and other release-related configs. src: https://github.com/ansible/pylibssh/blob/8b21ad7/docs/_ext/towncrier_draft_ext.py Resolves tox-dev#1639
webknjaz
added a commit
to webknjaz/tox
that referenced
this pull request
Jul 31, 2020
This change implements injecting the Towncrier draft change notes RST output into the Sphinx-managed docs site. It is heavily inspired by the work of @gaborbernat in tox and reinvented as a native Sphinx extension. Refs: * tox-dev#859 * ansible/pylibssh@f5f9ef1 In internally generates an unreleased changelog for the next unpublished project version (by calling `towncrier` in a subprocess) and provides it for injection as an RST directive called "towncrier-draft-entries". To start using it, first, add it to extensions in `conf.py`: extensions.append('towncrier_draft_ext') Then, optionally, set the global extensions options: towncrier_draft_autoversion_mode = 'scm-draft' # or: 'scm', 'draft', 'sphinx-version', 'sphinx-release' towncrier_draft_include_empty = True towncrier_draft_working_directory = PROJECT_ROOT_DIR towncrier_draft_config_path = 'pyproject.toml' # relative to cwd Their meaning is as follows: * towncrier_draft_autoversion_mode -- mechanism for the fallback version detection. It kicks in if, when using the directive, you don't specify the version argument and then will be passed to the `towncrier` invocation. Possible values are: * 'scm-draft' -- default, use setuptools-scm followed by a string "[UNRELEASED DRAFT]" * 'scm' -- use setuptools-scm * 'draft' -- use just a string "[UNRELEASED DRAFT]" * 'sphinx-version' -- use value of the "version" var in as set in `conf.py` * 'sphinx-release' -- use value of the "release" var in as set in `conf.py` * towncrier_draft_include_empty -- control whether the directive injects anything if there's no fragments in the repo. Boolean, defaults to `True`. * towncrier_draft_working_directory -- if set, this will be the current working directory of the `towncrier` invocation. * towncrier_draft_config_path -- path of the custom config to use for the invocation. Should be relative to the working directory. Not yet supported: the corresponding Towncrier CLI option is in their master but is not yet released. Don't use it unless you install a bleading-edge towncrier copy (or they make a release). Finally, use the directive in your RST source as follows: .. towncrier-draft-entries:: |release| [UNRELEASED DRAFT] The inline argument of the directive is what is passed to towncrier as a target version. It is optional and if not set, the fallback from the global config will be used. Pro tip: you can use RST substitutions like `|release|` or `|version|` in order to match the version with what's set in Sphinx and other release-related configs. src: https://github.com/ansible/pylibssh/blob/8b21ad7/docs/_ext/towncrier_draft_ext.py Resolves tox-dev#1639
webknjaz
added a commit
to webknjaz/tox
that referenced
this pull request
Jul 31, 2020
This change implements injecting the Towncrier draft change notes RST output into the Sphinx-managed docs site. It is heavily inspired by the work of @gaborbernat in tox and reinvented as a native Sphinx extension. Refs: * tox-dev#859 * ansible/pylibssh@f5f9ef1 In internally generates an unreleased changelog for the next unpublished project version (by calling `towncrier` in a subprocess) and provides it for injection as an RST directive called "towncrier-draft-entries". To start using it, first, add it to extensions in `conf.py`: extensions.append('towncrier_draft_ext') Then, optionally, set the global extensions options: towncrier_draft_autoversion_mode = 'scm-draft' # or: 'scm', 'draft', 'sphinx-version', 'sphinx-release' towncrier_draft_include_empty = True towncrier_draft_working_directory = PROJECT_ROOT_DIR towncrier_draft_config_path = 'pyproject.toml' # relative to cwd Their meaning is as follows: * towncrier_draft_autoversion_mode -- mechanism for the fallback version detection. It kicks in if, when using the directive, you don't specify the version argument and then will be passed to the `towncrier` invocation. Possible values are: * 'scm-draft' -- default, use setuptools-scm followed by a string "[UNRELEASED DRAFT]" * 'scm' -- use setuptools-scm * 'draft' -- use just a string "[UNRELEASED DRAFT]" * 'sphinx-version' -- use value of the "version" var in as set in `conf.py` * 'sphinx-release' -- use value of the "release" var in as set in `conf.py` * towncrier_draft_include_empty -- control whether the directive injects anything if there's no fragments in the repo. Boolean, defaults to `True`. * towncrier_draft_working_directory -- if set, this will be the current working directory of the `towncrier` invocation. * towncrier_draft_config_path -- path of the custom config to use for the invocation. Should be relative to the working directory. Not yet supported: the corresponding Towncrier CLI option is in their master but is not yet released. Don't use it unless you install a bleading-edge towncrier copy (or they make a release). Finally, use the directive in your RST source as follows: .. towncrier-draft-entries:: |release| [UNRELEASED DRAFT] The inline argument of the directive is what is passed to towncrier as a target version. It is optional and if not set, the fallback from the global config will be used. Pro tip: you can use RST substitutions like `|release|` or `|version|` in order to match the version with what's set in Sphinx and other release-related configs. src: https://github.com/ansible/pylibssh/blob/8b21ad7/docs/_ext/towncrier_draft_ext.py Resolves tox-dev#1639
webknjaz
added a commit
to sphinx-contrib/sphinxcontrib-towncrier
that referenced
this pull request
Aug 1, 2020
This change implements injecting the Towncrier draft change notes RST output into the Sphinx-managed docs site. It is heavily inspired by the work of @gaborbernat in tox and reinvented as a native Sphinx extension. Refs: * tox-dev/tox#859 * ansible/pylibssh@f5f9ef1 In internally generates an unreleased changelog for the next unpublished project version (by calling `towncrier` in a subprocess) and provides it for injection as an RST directive called "towncrier-draft-entries". To start using it, first, add it to extensions in `conf.py`: extensions.append('sphinxcontrib.towncrier') Then, optionally, set the global extensions options: towncrier_draft_autoversion_mode = 'scm-draft' # or: 'scm', 'draft', 'sphinx-version', 'sphinx-release' towncrier_draft_include_empty = True towncrier_draft_working_directory = PROJECT_ROOT_DIR towncrier_draft_config_path = 'pyproject.toml' # relative to cwd Their meaning is as follows: * towncrier_draft_autoversion_mode -- mechanism for the fallback version detection. It kicks in if, when using the directive, you don't specify the version argument and then will be passed to the `towncrier` invocation. Possible values are: * 'scm-draft' -- default, use setuptools-scm followed by a string "[UNRELEASED DRAFT]" * 'scm' -- use setuptools-scm * 'draft' -- use just a string "[UNRELEASED DRAFT]" * 'sphinx-version' -- use value of the "version" var in as set in `conf.py` * 'sphinx-release' -- use value of the "release" var in as set in `conf.py` * towncrier_draft_include_empty -- control whether the directive injects anything if there's no fragments in the repo. Boolean, defaults to `True`. * towncrier_draft_working_directory -- if set, this will be the current working directory of the `towncrier` invocation. * towncrier_draft_config_path -- path of the custom config to use for the invocation. Should be relative to the working directory. Not yet supported: the corresponding Towncrier CLI option is in their master but is not yet released. Don't use it unless you install a bleading-edge towncrier copy (or they make a release). Finally, use the directive in your RST source as follows: .. towncrier-draft-entries:: |release| [UNRELEASED DRAFT] The inline argument of the directive is what is passed to towncrier as a target version. It is optional and if not set, the fallback from the global config will be used. Pro tip: you can use RST substitutions like `|release|` or `|version|` in order to match the version with what's set in Sphinx and other release-related configs. src: https://github.com/ansible/pylibssh/blob/8b21ad7/docs/_ext/towncrier_draft_ext.py
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
:user:extlinks for changelog entries to link to contributorsGithub profile
pyon windows #858see example output at https://tox-gaborbernat.readthedocs.io/en/doc-impr (or deep dive http://tox-gaborbernat.readthedocs.io/en/doc-impr/changelog.html)