docs: Update template README.rst to match OEP-55 Guidelines #241
Conversation
|
Current dependencies on/for this PR:
This comment was auto-generated by Graphite. |
feanil
force-pushed
the
feanil/update_readme
branch
from
e3b6385 to
d23e691
Compare
feanil
force-pushed
the
feanil/update_readme
branch
from
d23e691 to
490d9e8
Compare
feanil
force-pushed
the
feanil/update_readme
branch
from
490d9e8 to
291fc58
Compare
|
|
||
| Overview (please modify) |
There was a problem hiding this comment.
I wonder if there should be some replacement for "(please modify)". Could be something like:
.. note::
This README was auto-generated. The "Purpose" needs to be manually updated, and the rest of the README should be reviewed for potential updates.
There was a problem hiding this comment.
@feanil: Can you confirm your intention? Not sure if you intentionally don't want to add a note, or if you just missed this. Thanks.
Also note that if you read the README, it is clear that it should be updated. But, I'm just wondering if anything can make it more clear for cases where your eyes are passing over it, but you aren't actually reading it. It might be that mu suggestion is no better than what is there.
There was a problem hiding this comment.
Missed this the first time, I'll add it along with the other suggestions.
python-template/{{cookiecutter.placeholder_repo_name}}/README.rst
Outdated
Show resolved
Hide resolved
feanil
force-pushed
the
feanil/update_readme
branch
from
ffbf2ad to
f0fddb9
Compare
There was a problem hiding this comment.
After reading the README Spec sheet, this looks good! It would be great to have this as a standard everywhere.
How many more repos do we need to do this for? Do we have a ticket anywhere to update READMEs to fit this format, where we can track the repos that still need their READMEs updated?
| Deploying | ||
| ========= | ||
|
|
||
| How can a new user, go about deploying this component? Is it just a few commands? Is there a larger how-to that should be linked here? |
There was a problem hiding this comment.
| How can a new user, go about deploying this component? Is it just a few commands? Is there a larger how-to that should be linked here? | |
| How can a new user go about deploying this component? Is it just a few commands? Is there a larger how-to that should be linked here? |
|
|
||
| For details on how to deploy this component, checkout the `deployment how-to`_ | ||
|
|
||
| .. _deployment how-to: https://docs.openedx.org/projects/this-project/how-tos/how-to-deploy-this-component.html |
There was a problem hiding this comment.
Maybe {{cookiecutter.repo_name}} in here, too?
| .. _deployment how-to: https://docs.openedx.org/projects/this-project/how-tos/how-to-deploy-this-component.html | |
| .. _deployment how-to: https://docs.openedx.org/projects/{{cookiecutter.repo_name}}/how-tos/how-to-deploy-this-component.html |
Fix a typo and add a header to clearly indicate that the readme should be read and updated after it has been generated.
|
|
||
| Documentation | ||
| ************* | ||
| The ``README.rst`` file should start with a brief description of the repository and its purpose. |
There was a problem hiding this comment.
I know this is merged already, but thinking about linting, and also for clarification: what if we started each paragraph like this with PLACEHOLDER:, then linted for the appearance of that word in READMEs? It would help everyone (maintainer and readers of the file) understand that the paragraph is just a placeholder, leave a strong signal that something needs to be done, and be easily lintable.
There was a problem hiding this comment.
Actually, I will make a PR with this change, and we can discuss there.
Description:
Update the README.rst to match guidance in OEP-55
Merge checklist: