docs refactoring: towncrier draft + sphinx as an ext #1639
Labels
Comments
|
Sure 😃 |
webknjaz
added a commit
to webknjaz/tox
that referenced
this issue
Jul 31, 2020
webknjaz
added a commit
to webknjaz/tox
that referenced
this issue
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
6 tasks
webknjaz
added a commit
to webknjaz/tox
that referenced
this issue
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 issue
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
|
After consideration, we'll keep this internal for now. We can discuss in a years time or so, considering how the plugin project evolves. |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
So I happened to borrow the idea of embedding the draft Towncrier output into Sphinx docs and turned it into a native Sphinx extension: ansible/pylibssh@f5f9ef1.
The basic use is:
(for example, there's also configuration options and defaults)
@gaborbernat would you want it here? It basically could replace the hack this generating a gitignored file. I'm considering releasing it as a standalone dist but right now it's only available as vendored copy-paste.
The text was updated successfully, but these errors were encountered: