Allow skipping date in the version header

[maxking]

So, the intent for me here is to make scriv collect as part of regular documentation build such that the "latest" version of the documentation shows the the unreleased changes made so far.

For example, Scriv's documentation currently has only a placeholder which says

See the fragment files in the [changelog.d directory](https://github.com/nedbat/scriv/tree/master/changelog.d).

IMO it would be slightly better if instead of that we could add scriv collect to the commands in docs testenv for docs.

Doing that with scriv reuses the currently released version number (0.13.0) since it looks like the version number hasn't been updated to 0.14.0-dev or something to signify a dev build. But either way, I can override the version with scriv collect --verison next.

Since it is unreleased, i'd like it to skip the date header though, since it doesn't make sense in the context.

Do you think it is a good enough use case to support another flag, something like --skip-date, to skip addition of date?

[maxking]

Hey @nedbat, any thoughts about this issue?

[nedbat]

For your use, maybe the best thing would be --header=Next or whatever to just set the entire text of the header.

[nedbat]

But also, if you run the command again, it should add content to that header, rather than making a second Next heading, right?

[maxking]

Actually, I didn't notice the --header will override it. I think that should solve my use case.

But also, if you run the command again, it should add content to that header, rather than making a second Next heading, right?

So, my idea is to generate the Next section during the docs build. In the source, we will keep only the fragments until a new release happens. So, ideally, there wouldn't be a situation where we have a Next heading and also fragments.

[nedbat]

Actually, I didn't notice the --header will override it. I think that should solve my use case.

Sorry, I wasn't clear: there is no --header option yet.

So, my idea is to generate the Next section during the docs build. In the source, we will keep only the fragments until a new release happens. So, ideally, there wouldn't be a situation where we have a Next heading and also fragments.

I don't understand the flow here. When does the docs build happen? I thought you wanted a way to gradually collect entries in an "Unreleased" or "Next" section, the way people do manually? Can you explain what you mean by a "docs build"?

[maxking]

I don't understand the flow here. When does the docs build happen? I thought you wanted a way to gradually collect entries in an "Unreleased" or "Next" section, the way people do manually? Can you explain what you mean by a "docs build"?

"docs build" essentially mean when we generate HTML using sphinx form the .rst (or whatever), most importantly on readthedocs for me.

The idea is that I will keep all the entries in changelog.d until a release, but before we do sphinx-build (which happens on each commit), we will run scriv collect --header="Next" such that all the un-release entries also show up in the NEWS.rst file. The changes made by scriv collect --header="Next" are never checked in VCS. Only when we are ready for a reelease, we will do a scriv collect with the right version number and commit then changes to VCS, cleaning out the changelogs.d.

Hopefully, that explains the flow better.

[nedbat]

Thanks for the explanation, and sorry for the delay.

This is now implemented in c87162a, as collect --title=TEXT.

[nedbat]

This is now released as part of scriv 0.17.0.