Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

use markdown default template in markdown docs #546

Merged
merged 2 commits into from
Sep 15, 2023
Merged

use markdown default template in markdown docs #546

merged 2 commits into from
Sep 15, 2023

Conversation

EFord36
Copy link
Contributor

@EFord36 EFord36 commented Sep 15, 2023

Description

Closes #545

Uses the default markdown templates introduced in #483 in the markdown docs rather than specifying a custom template.

One option for resolving #545 - thought I'd provide a PR as it was simple, but happy if you want to resolve in a different way (e.g. an explicit block in the docs discussing the default markdown template vs the custom one currently used).

Checklist

  • Make sure changes are covered by existing or new tests.
  • For at least one Python version, make sure local test run is green.
  • 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.

@EFord36 EFord36 requested a review from a team as a code owner September 15, 2023 10:33
@@ -13,7 +13,6 @@ build:
python: "3.11"

python:
system_packages: False
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this was removed from RTD 2023-08-29

https://blog.readthedocs.com/drop-support-system-packages/

We need this change to build the docs

@EFord36
Copy link
Contributor Author

EFord36 commented Sep 15, 2023

I looked into my problem with check_newsfragment, and it was that I had edited it with vim and left a .545.doc.un~ hanging around, which apparently confuses towncrier.check. Maybe that should be a new issue? In any case, it isn't a problem for this PR (that file was never committed anyway).

I removed the issue I was having from the description for clarity - preserving below for transparency:

check_newsfragment issue

One problem at the moment - when I run `nox -e pre_commit check_newsfragment`

I get a failure on check_newsfragment that I don't understand: ValueError: multiple files for 545.doc in /Users/ktdb353/workplace/towncrier/src/towncrier/newsfragments . I'll debug this but wanted to get this PR out close to #545 being opened, and if it's just something wrong with the news snippet, this approach in general could be considered.

Copy link
Member

@adiroiban adiroiban left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. It looks very good.

https://towncrier--546.org.readthedocs.build/en/546/markdown.html

I hope that in the future we can also have a standard directory name for these files.

I see now that towncrier uses newsfragments but this documentation is suggesting changelog.d

I prefer something like release-notes/123.fix :)


For the other issue, is best to open a separate ticket, if you want o work on it.

The idea is that towncrie is expected to be used by developers, so there isn't much effort into making the errors "user friendly"

but of course, we can and should improve the error reporting.

@adiroiban adiroiban merged commit 239f841 into twisted:trunk Sep 15, 2023
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Markdown docs use 'custom' template and don't show/mention default available
2 participants