[WIP] Some docssssss by hawkowl · Pull Request #89 · twisted/towncrier

hawkowl · 2017-08-21T12:04:33Z

No description provided.

codecov-io · 2017-08-21T12:17:04Z

Codecov Report

Merging #89 into master will decrease coverage by 0.17%.
The diff coverage is 80%.

@@            Coverage Diff             @@
##           master      #89      +/-   ##
==========================================
- Coverage    90.3%   90.13%   -0.18%     
==========================================
  Files          12       12              
  Lines         454      456       +2     
  Branches       56       57       +1     
==========================================
+ Hits          410      411       +1     
  Misses         27       27              
- Partials       17       18       +1

Impacted Files	Coverage Δ
src/towncrier/_settings.py	`80% <ø> (ø)`	⬆️
src/towncrier/__init__.py	`87.3% <80%> (-1.23%)`	⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8e6fc19...35db954. Read the comment docs.

wcooley · 2017-09-11T20:56:41Z

docs/configuration.rst

+``[tool.towncrier]``
+--------------------
+
+All configuration for ``towncrier`` sits inside ``pyproject.toml``, under the ``tool.towncrier`` namespace.


Consider also mentioning PEP-518 to explain why the config is in a file named pyproject.toml.

hynek · 2017-10-05T09:14:59Z

MANIFEST.in

 recursive-include src *.rst

 exclude bin
+exclude docs


I think you want 2x prune here. IIRC exclude only works on files.

hynek · 2017-10-05T09:16:50Z

MANIFEST.in

+exclude docs
 exclude src/towncrier/newsfragments

 recursive-exclude bin *


These three lines become obsolete then.

hynek · 2017-10-05T09:23:13Z

docs/configuration.rst

+=======================
+
+``towncrier`` has many knobs and switches you can use, to customise it to your project's needs.
+The setup in the `Quick Start <quickstart.html>`_ doesn't touch on many, but this document will detail each of these options for you!


Does this work?

:doc:`quickstart`

Should do the trick.

hynek · 2017-10-05T09:23:37Z

docs/configuration.rst

+``towncrier`` has many knobs and switches you can use, to customise it to your project's needs.
+The setup in the `Quick Start <quickstart.html>`_ doesn't touch on many, but this document will detail each of these options for you!
+
+For how to perform common customisation tasks, see `Customisation <customisation/index.html>`_.


Same or

:doc:`Customization <customization/index>`

if you don't want to use the name of the headline.

Or ref:Customization to avoid the …/index.

hynek · 2017-10-05T09:25:37Z

docs/customisation/index.rst

+=========================
+
+``towncrier`` can be customised to suit your project's needs.
+These pages should describe common customisation tasks, while if you want a reference, see `Configuration <../configuration.html>`_.


You get the idea. :)

htgoebel

Strictly this pull-request is not only about docs, but also adds a new option --name.

htgoebel · 2017-10-05T12:20:26Z

docs/configuration.rst

+``towncrier`` has many knobs and switches you can use, to customise it to your project's needs.
+The setup in the `Quick Start <quickstart.html>`_ doesn't touch on many, but this document will detail each of these options for you!
+
+For how to perform common customisation tasks, see `Customisation <customisation/index.html>`_.


Or ref:Customization to avoid the …/index.

htgoebel · 2017-10-05T12:21:49Z

docs/configuration.rst

+--------------------
+
+All configuration for ``towncrier`` sits inside ``pyproject.toml``, under the ``tool.towncrier`` namespace.
+Please see `the TOML GitHub repo <https://github.com/toml-lang/toml>`_ for how to write TOML.


What about some works about TOML like. "TOML looks much like .ini files, but has a defined syntax."

htgoebel · 2017-10-05T12:26:09Z

docs/configuration.rst

+- ``package`` -- The package name of your project. (Python projects only)
+- ``package_dir`` -- The folder your package lives. ``./`` by default, some projects might need to use ``src``. (Python projects only)
+- ``newsfile`` -- The filename of your news file. ``NEWS.rst`` by default.
+- ``fragment_directory`` -- If you are not storing your newsfragments in your Python package, or aren't using Python, this is the path to where your newsfragments will be put.


What about "the path to where your newsfragments will be put – defaults to XXX"

"will be put" by whom? by towncrier? Maybe better "will be collected" or "where towncrier will search for newsfragments"?

Buh, this is a long line.

This option actually is named just directory.

htgoebel · 2017-10-05T12:27:25Z

docs/configuration.rst

+- ``package_dir`` -- The folder your package lives. ``./`` by default, some projects might need to use ``src``. (Python projects only)
+- ``newsfile`` -- The filename of your news file. ``NEWS.rst`` by default.
+- ``fragment_directory`` -- If you are not storing your newsfragments in your Python package, or aren't using Python, this is the path to where your newsfragments will be put.
+- ``template`` -- Path to an alternate template for generating the newsfile, if you have one.


"Path to the template for generating the newsfile. Defaults to a build-in template."

htgoebel · 2017-10-05T12:30:26Z

docs/configuration.rst

+- ``newsfile`` -- The filename of your news file. ``NEWS.rst`` by default.
+- ``fragment_directory`` -- If you are not storing your newsfragments in your Python package, or aren't using Python, this is the path to where your newsfragments will be put.
+- ``template`` -- Path to an alternate template for generating the newsfile, if you have one.
+- ``start_line`` -- The magic string that ``towncrier`` looks for when considering where the release notes should start. ``.. towncrier release notes start`` by default.


Use Sphinx feature:

:program:`towncrier`

htgoebel · 2017-10-05T12:52:52Z

docs/quickstart.rst

+
+We can then see our news fragments compiled by running ``towncrier`` in draft mode::
+
+    $ towncrier --draft


General: Please do not put $ in front of example commands. This inhibits easy copy-and-paste.

htgoebel · 2017-10-05T12:53:42Z

docs/quickstart.rst

+
+You should get an output similar to this::
+
+    $ towncrier --draft


Here the $ is okay since it mixed commands and output.

htgoebel · 2017-10-05T12:56:17Z

docs/quickstart.rst

+
+    $ towncrier
+
+This command will remove the news files (with ``git rm``) and append the built news to the filename specified in ``pyproject.toml``, and then stage the news file changes (with ``git add``).


will remove the news fragments, I assume

htgoebel · 2017-10-05T12:56:47Z

docs/quickstart.rst

+Finale
+------
+
+You should now have everything you need to get started with ``towncrier``!


:program:towncrier

htgoebel · 2017-10-05T12:57:47Z

src/towncrier/__init__.py

 @click.option('--version', 'project_version', default=None)
 @click.option('--date', 'project_date', default=None)
+@click.option('--name', 'project_name', default=None,
+              help="The name of your project, to override autodiscovery.")


"The name of your project (default: autodiscovery)".

htgoebel · 2018-08-28T14:20:46Z

@hawkowl Any progress on the documentation?

adiroiban · 2022-02-13T11:29:29Z

FYI There is #368 which tries to merge this code so that we can progress with the documentation.

adiroiban · 2022-04-02T14:16:45Z

The documentation was merged into the main branch and integrated with read the docs https://towncrier.readthedocs.io/en/latest/

adiroiban · 2022-07-16T13:36:10Z

I am going to close this as most of the changes were already merged.

hawkowl added 5 commits August 21, 2017 20:46

Initial frame

55ae60e

some docs

5bc9cf3

--name is good

31a5efb

fixes

84b80ec

more fixes

15cea95

write some docs

35db954

wcooley reviewed Sep 11, 2017

View reviewed changes

This was referenced Oct 4, 2017

Who creates the fragments? #4

Closed

Questions about the readme #83

Closed

Readme should describe the intented workflow #86

Open

Make path to newsfragments directory configurable #87

Closed

Document title_format and template #53

Closed

hynek reviewed Oct 5, 2017

View reviewed changes

htgoebel suggested changes Oct 5, 2017

View reviewed changes

Give zsh-compatible echo command in quickstart (#268)

867c1e8

altendky mentioned this pull request Mar 13, 2021

Add manpage #326

Closed

adiroiban mentioned this pull request Feb 13, 2022

docs(Configuration): Move docs to the main branch and add info about custom fragment types. #368

Merged

adiroiban mentioned this pull request Feb 13, 2022

Rework CONTRIBUTING file #343

Merged

adiroiban closed this Jul 16, 2022


		We can then see our news fragments compiled by running ``towncrier`` in draft mode::

		$ towncrier --draft


		You should get an output similar to this::

		$ towncrier --draft


		$ towncrier

		This command will remove the news files (with ``git rm``) and append the built news to the filename specified in ``pyproject.toml``, and then stage the news file changes (with ``git add``).

Conversation

hawkowl commented Aug 21, 2017

Uh oh!

codecov-io commented Aug 21, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

htgoebel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

htgoebel commented Aug 28, 2018

Uh oh!

adiroiban commented Feb 13, 2022

Uh oh!

adiroiban commented Apr 2, 2022

Uh oh!

adiroiban commented Jul 16, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

codecov-io commented Aug 21, 2017 •

edited

Loading