Merge pull request #435 from twisted/docs

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,3 +8,6 @@
 * [ ] Create a file in `src/towncrier/newsfragments/`. Describe your
   change and include important information. Your change will be included in the public release notes.
 * [ ] Make sure all GitHub Actions checks are green (they are automatically checking all of the above).
+* [ ] Ensure `docs/tutorial.rst` is still up-to-date.
+* [ ] If you add new **CLI arguments** (or change the meaning of existing ones), make sure `docs/cli.rst` reflects those changes.
+* [ ] If you add new **configuration options** (or change the meaning of existing ones), make sure `docs/configuration.rst` reflects those changes.

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2015-2016, Amber Brown, meejah
+Copyright (c) 2015, Amber Brown and the towncrier contributors
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.rst

@@ -1,203 +1,45 @@
 Hear ye, hear ye, says the ``towncrier``
 ========================================
 
-.. image:: https://img.shields.io/github/workflow/status/twisted/towncrier/CI/trunk
-    :alt: GitHub Actions
-    :target: https://github.com/twisted/towncrier/actions?query=branch%3Atrunk
+.. image:: https://img.shields.io/badge/Docs-Read%20The%20Docs-black
+   :alt: Documentation
+   :target: https://towncrier.readthedocs.io/
 
-.. image:: https://img.shields.io/codecov/c/github/twisted/towncrier/trunk
-    :alt: Codecov
-    :target: https://app.codecov.io/gh/twisted/towncrier/branch/trunk
+.. image:: https://img.shields.io/badge/license-MIT-C06524
+   :alt: License: MIT
+   :target: https://github.com/twisted/towncrier/blob/trunk/LICENSE
 
+.. image:: https://img.shields.io/pypi/v/towncrier
+   :alt: PyPI release
+   :target: https://pypi.org/project/towncrier/
 
-``towncrier`` is a utility to produce useful, summarised news files for your project.
-Rather than reading the Git history as some newer tools to produce it, or having one single file which developers all write to, ``towncrier`` reads "news fragments" which contain information `useful to end users`.
+``towncrier`` is a utility to produce useful, summarized news files (also known as changelogs) for your project.
+
+Rather than reading the Git history, or having one single file which developers all write to and produce merge conflicts, ``towncrier`` reads "news fragments" which contain information useful to **end users**.
 
 Used by `Twisted <https://github.com/twisted/twisted>`_, `pytest <https://github.com/pytest-dev/pytest/>`_, `pip <https://github.com/pypa/pip/>`_, `BuildBot <https://github.com/buildbot/buildbot>`_, and `attrs <https://github.com/python-attrs/attrs>`_, among others.
 
+While the command line tool ``towncrier`` works on Python 3.7+ only, as long as you don't use any Python-specific affordances (like auto-detection of the project version), it is usable with **any project type** on **any platform**.
+
 
 Philosophy
 ----------
 
 ``towncrier`` delivers the news which is convenient to those that hear it, not those that write it.
 
 That is, by duplicating what has changed from the "developer log" (which may contain complex information about the original issue, how it was fixed, who authored the fix, and who reviewed the fix) into a "news fragment" (a small file containing just enough information to be useful to end users), ``towncrier`` can produce a digest of the changes which is valuable to those who may wish to use the software.
-These fragments are also commonly called "topfiles" or "newsfiles" in Twisted parlance.
+These fragments are also commonly called "topfiles" or "newsfiles".
 
 ``towncrier`` works best in a development system where all merges involve closing a ticket.
 
+To get started, check out our `tutorial <https://towncrier.readthedocs.io/en/latest/tutorial.html>`_!
 
-Quick Start
------------
-
-Install from PyPI::
-
-    python3 -m pip install towncrier
-
-.. note::
-
-   ``towncrier``, as a command line tool, works on Python 3.7+ only.
-   It is usable by projects written in other languages, provided you specify the project version either in the configuration file or on the command line.
-   For Python-compatible projects, the version can be discovered automatically.
-
-In your project root, add a ``towncrier.toml`` or a ``pyproject.toml`` file (if both files exist, the first will take precedence).
-You can configure your project in two ways.
-To configure it via an explicit directory, add:
-
-.. code-block:: toml
-
-    [tool.towncrier]
-    directory = "changes"
-
-Alternatively, to configure it relative to a (Python) package directory, add:
-
-.. code-block:: toml
-
-    [tool.towncrier]
-    package = "mypackage"
-    package_dir = "src"
-    filename = "NEWS.rst"
-
-.. note::
-
-    ``towncrier`` will also look in ``pyproject.toml`` for configuration if ``towncrier.toml`` is not found.
-
-For the latter, news fragments (see "News Fragments" below) should be in a ``newsfragments`` directory under your package.
-Using the above example, your news fragments would be ``src/myproject/newsfragments/``).
-
-.. tip::
-
-    To prevent git from removing the ``newsfragments`` directory, make a ``.gitignore`` file in it with::
-
-        !.gitignore
-
-    This will keep the folder around, but otherwise "empty".
-
-``towncrier`` needs to know what version your project is, and there are three ways you can give it:
-
-- For Python-compatible projects, a ``__version__`` in the top level package.
-  This can be either a string literal, a tuple, or an `Incremental <https://github.com/hawkowl/incremental>`_ version.
-
-- Manually passing ``--version=<myversionhere>`` when interacting with ``towncrier``.
-
-- Definining a ``version`` option in a configuration file:
-
-.. code-block:: ini
-
-    [tool.towncrier]
-    # ...
-    version = "1.2.3"  # project version if maintained separately
-
-To create a new news fragment, use the ``towncrier create`` command.
-For example::
-
-    towncrier create 123.feature
-
-If a news fragment is not tied to an issue, use `+` as the basename (a random hash will be added to the filename to keep it unique):
-
-    towncrier create +.feature
-
-To produce a draft of the news file, run::
-
-    towncrier build --draft
-
-To produce the news file for real, run::
-
-    towncrier build
-
-This command will remove the news files (with ``git rm``) and append the built news to the filename specified by the ``filename`` configuration option, and then stage the news file changes (with ``git add``).
-It leaves committing the changes up to the user.
-
-If you wish to have content at the top of the news file (for example, to say where you can find the tickets), put your text above a rST comment that says::
-
-  .. towncrier release notes start
-
-``towncrier`` will then put the version notes after this comment, and leave your existing content that was above it where it is.
-
-
-News Fragments
---------------
-
-``towncrier`` has a few standard types of news fragments, signified by the file extension.
-These are:
-
-- ``.feature``: Signifying a new feature.
-- ``.bugfix``: Signifying a bug fix.
-- ``.doc``: Signifying a documentation improvement.
-- ``.removal``: Signifying a deprecation or removal of public API.
-- ``.misc``: A ticket has been closed, but it is not of interest to users.
-
-The start of the filename is the ticket number, and the content is what will end up in the news file.
-For example, if ticket #850 is about adding a new widget, the filename would be ``myproject/newsfragments/850.feature`` and the content would be ``myproject.widget has been added``.
-
-
-Further Options
----------------
-
-Towncrier has the following global options, which can be specified in the toml file:
-
-.. code-block:: toml
-
-    [tool.towncrier]
-    package = ""
-    package_dir = "."
-    single_file = true  # if false, filename is formatted like `title_format`.
-    filename = "NEWS.rst"
-    directory = "directory/of/news/fragments"
-    version = "1.2.3"  # project version if maintained separately
-    name = "arbitrary project name"
-    template = "path/to/template.rst"
-    start_string = "Text used to detect where to add the generated content in the middle of a file. Generated content added after this text. Newline auto added."
-    title_format = "{name} {version} ({project_date})"  # or false if template includes title
-    issue_format = "format string for {issue} (issue is the first part of fragment name)"
-    underlines = "=-~"
-    wrap = false  # Wrap text to 79 characters
-    all_bullets = true  # make all fragments bullet points
-    orphan_prefix = "+"   # Prefix for orphan news fragment files, set to "" to disable.
-
-If ``single_file`` is set to ``true`` or unspecified, all changes will be written to a single
-fixed newsfile, whose name is literally fixed as the ``filename`` option. In each run of ``towncrier build``,
-content of new changes will append at the top of old content, and after ``start_string`` if the
-``start_string`` already appears in the newsfile. If the corresponding ``top_line``, which is formatted
-as the option 'title_format', already exists in newsfile, ``ValueError`` will be raised to remind
-you "already produced newsfiles for this version".
-
-If ``single_file`` is set to ``false`` instead, each versioned ``towncrier build`` will generate a
-separate newsfile, whose name is formatted as the pattern given by option ``filename``.
-For example, if ``filename="{version}-notes.rst"``, then the release note with version "7.8.9" will
-be written to the file "7.8.9-notes.rst". If the newsfile already exists, its content
-will be overwriten with new release note, without throwing a ``ValueError`` warning.
-
-If ``title_format`` is unspecified or an empty string, the default format will be used.
-If set to ``false``, no title will be created.
-This can be useful if the specified template creates the title itself.
-
-Furthermore, you can customize each of your own fragment types using:
-
-.. code-block:: toml
-
-    [tool.towncrier]
-	# To add custom fragment types, with default setting, just add an empty section.
-    [tool.towncrier.fragment.feat]
-    [tool.towncrier.fragment.fix]
-
-	# Custom fragment types can have custom attributes
-	# that are used when rendering the result based on the template.
-    [tool.towncrier.fragment.chore]
-        name = "Other Tasks"
-        showcontent = false
-
-
-
-Automatic pull request checks
------------------------------
-
-To check if a feature branch adds at least one news fragment, run::
-
-    towncrier check
-
-By default this compares the current branch against ``origin/main``. You can use ``--compare-with`` if the trunk is named differently::
+.. links
 
-    towncrier check --compare-with origin/master
+Project Links
+-------------
 
-The check is automatically skipped when the main news file is modified inside the branch as this signals a release branch that is expected to not have news fragments.
+- **PyPI**: https://pypi.org/project/towncrier/
+- **Documentation**: https://towncrier.readthedocs.io/
+- **News**: https://github.com/twisted/towncrier/blob/trunk/NEWS.rst
+- **License**: `MIT <https://github.com/twisted/towncrier/blob/trunk/LICENSE>`_

RELEASE.rst

@@ -1,5 +1,5 @@
-Releasing
-=========
+Release Process
+===============
 
 ..  note::
     Commands are written with Linux in mind and a ``venv`` located in ``venv/``.

docs/cli.rst

@@ -0,0 +1,87 @@
+Command Line Reference
+======================
+
+The following options can be passed to all of the commands that explained below:
+
+.. option:: --config FILE_PATH
+
+   Pass a custom config file at ``FILE_PATH``.
+
+   Default: ``towncrier.toml`` or ``pyproject.toml`` file.
+   If both files exist, the first will take precedence
+
+.. option:: --dir PATH
+
+   Build fragment in ``PATH``.
+
+   Default: current directory.
+
+
+``towncrier build``
+-------------------
+
+Build the combined news file from news fragments.
+``build`` is also assumed if no command is passed.
+
+.. option:: --draft
+
+   Only render news fragments to standard output.
+   Don't write to files, don't check versions.
+
+.. option:: --name NAME
+
+   Use `NAME` as project name in the news file.
+   Can be configured.
+
+.. option:: --version VERSION
+
+   Use ``VERSION`` in the rendered news file.
+   Can be configured or guessed (default).
+
+.. option:: --date DATE
+
+   The date in `ISO format <https://xkcd.com/1179/>`_ to use in the news file.
+
+   Default: today's date
+
+.. option:: --yes
+
+   Do not ask for confirmations.
+   Useful for automated tasks.
+
+
+``towncrier create``
+--------------------
+
+Create a news fragment in the directory that ``towncrier`` is configured to look for fragments::
+
+   $ towncrier create 123.bugfix.rst
+
+``towncrier create`` will enforce that the passed type (e.g. ``bugfix``) is valid.
+
+.. option:: --content, -c CONTENT
+
+   A string to use for content.
+   Default: an instructive placeholder.
+
+.. option:: --edit
+
+   Create file and start `$EDITOR` to edit it right away.`
+
+
+``towncrier check``
+-------------------
+
+To check if a feature branch adds at least one news fragment, run::
+
+   $ towncrier check
+
+The check is automatically skipped when the main news file is modified inside the branch as this signals a release branch that is expected to not have news fragments.
+
+By default, ``towncrier`` compares the current branch against ``origin/main`` (and falls back to ``origin/master`` with a warning if it exists, *for now*).
+
+.. option:: --compare-with REMOTE-BRANCH
+
+   Use ``REMOTE-BRANCH`` instead of ``origin/main``::
+
+      $ towncrier check --compare-with origin/trunk

docs/conf.py

@@ -84,7 +84,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "furo"
 
 # 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
@@ -97,21 +97,6 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
 
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    "**": [
-        "about.html",
-        "navigation.html",
-        "relations.html",  # needs 'show_related': True theme option to display
-        "searchbox.html",
-        "donate.html",
-    ]
-}
-
 
 # -- Options for HTMLHelp output ------------------------------------------