You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In general, it seems like a common practice to have a CONTRIBUTING.rst file in the root of each repo. This helps users to get started. Also Github's Settings -> Community Option checks for the presence of one.
Describe the solution you would like to see for your use-case
One could add a default CONTRIBUTING.RST and also reference this file from the Sphinx index. Github provides several examples and there are others on the net.
The text was updated successfully, but these errors were encountered:
I have added a series of PRs to address this issue, by revamping PyScaffold's own CONTRIBUTING.rst (#468 and #471) and then using it as a reference to create a template for new projects (#470).
There were a few things that I was not 100% sure:
In order to improve CONTRIBUTING.rst, I have created a dev-guide (Add a dev guide to docs, to help potential contributors (2nd step #376) #467), but it shares a lot of content with the extension documentation. The most correct solution in this situation would be changing the extension documentation to remove the repeated content and just refer using a link to the dev-guide. However, this solution might be confusing for extension creators (they don't need to know how PyScaffold internal architecture works). Moreover, if the core concepts are not in the same page as the extensions, readers might be inclined to skip them... The solution I found was to separate the repeated code (Split extensions.rst into re-usable files and add pipeline image (1st step #376) #466) and use a include statement in sphinx to avoid double bookkeeping and inconsistency. This might not be ideal
The proposed template depends on a series of choices from the package developer (e.g., where the code is being hosted, if they are using a public package index, etc). The way I worked around this issue was to add a series of TODO items to the template guiding the user to review it before compiling the docs (I also added a configuration to make Sphinx raise a warn for every TODO statement left in the docs).
I tried to make the proposed template generic for open source and private projects, but I don't really know if it reads nicely for private projects...
If that is the case, I was planning to release v4.1...
So far, we have accumulated as new features/changes: a new linkcheck task in tox.ini, updated licenses (0BSD for generated code + new tamplate), better coveralls support from the Cirrus CI template, and the new CONTRIBUTING.
Should we wait a bit for something else? I think the #447 can wait another minor release...