requests-mock requires git repository to build doc

[thomasgoirand]

Hi,

When building the Debian package for requests-mock, it failed to build from source, because it requires a git repository when building the doc. The only way I found to fix this is to disable the reno sphinx extension from doc's conf.py.

Please fix this, so that distributions can also include in the doc package release notes from your project.

[jamielennox]

Hey Thomas,

So the extension that is causing the problem is https://docs.openstack.org/reno/latest/ which is including a ChangeLog into the generated docs at source build time. I'm not wedded to the application, but I prefer something tied into the git workflow.

How does the rest of OpenStack projects get managed on debian?

If I can figure out how to prebuild the docs and include them in the published tarball is that sufficient or do you need to actually build them from source?

[pbasista]

Maybe related: The release notes for the latest version 1.6.0 are unavailable at the readthedocs.io website. They can probably be inferred from the last commits in the releasenotes/notes/ directory within the repository, but I was not able to find a single place within the repository where they would already be extracted into a presentable form.

Their unavailability on the readthedocs.io website is perhaps a consequence of some build job not being run. But it also raises a question about whether the current workflow is appropriate.

It seems to me that maintaining a single file with release notes is simpler than keeping them in multiple files which require post-processing in order to contain the details about the affected release versions. Moreover, the final form seems to only be available on the readthedocs.io website and not in the repository itself. If some form of packaging requires release notes, it is necessary to include post-processing tools into the packaging pipeline. This is a complication which can easily be avoided by using simple text file for release notes.

What are the benefits of using the current workflow for maintaining release notes? Do they outweigh the above mentioned disadvantages?