-
Notifications
You must be signed in to change notification settings - Fork 24
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
Embed README in index.rst #65
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks fantastic! The 'contents' in the top right of the page with options to navigate to the installation instructions is super helpful, and I agree that the separate 'Installation Guide' page is not needed with these changes. Thanks so much for setting this up!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed with Teagan - this looks fantastic, thanks so much for setting it up @anissa111
Editing to add - my only concern is that the README is copied over, so if we make changes to the main README for the repo, they won't get automatically transferred, which could cause pain points with version control. Definitely not the end of the world, but something to be aware of.
Just to clarify, is the docs/README automatically generated and added to the documentation any time the normal README gets updated? If it's actually a copy that needs to be manually updated, maybe we could adjust that; if it's automatically maintained then I think this should be good to merge in... |
Installation Guide <install.rst> | ||
|
||
More details can be found in the main repository `README <https://github.com/TeaganKing/CUPiD/blob/main/README.md>`_ . | ||
.. include:: README.md |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this means line shows that this is pulling in README.md as it is generated on the main page, rather than creating a duplicate. So, I think this is good to merge in. Does that make sense to you, @rmshkv ? Please do let me know if I'm misinterpreting this! :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi! Sorry I missed your earlier comment. Yes, it is pulling the README.md each time the documentation is generated. It does technically duplicate the file, but only for the duration of the documentation creation, it's not something that has to be maintained in parallel or anything.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fantastic! That sounds like a great strategy.
By the way, @mnlevy1981 mentioned that his last comment was a somewhat minor thing-- if it's easy to address this morning, great, if not, maybe we can just merge this in as is so that we can get Lev's PR in today as well.
docs/conf.py
Outdated
# Remove any images from the first line of the README | ||
with open('README.md', 'r') as f: | ||
readme1 = f.readline() | ||
readme1 = re.sub('<.*?> ', '', readme1) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does it make sense to be more specific in your regular expression? Would
readme1 = re.sub('<img.*?> ', '', readme1)
work for removing images from this line while allowing us to still include raw html at a later date? I don't work with markdown much, so maybe it doesn't matter much, but if we wanted to wrap all of the <img src="images/logo.png" alt="CUPiD Logo" width=100 /> CUPiD: CESM Unified Postprocessing and Diagnostics
in HTML (maybe we add a link to the website now that we have documentation?) then the current regular expression will strip out the whole line
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure! I currently can't think of a scenario where you'd want to use html instead of markdown syntax except for images, but there's no harm in being more specific!
Related to: #38 (comment)
Summary of changes:
README.md
README.md
indocs/index.rst
by copyingCUPiD/README.md
into the docs directory indocs/conf.py
and removes the logo in the top header because having an image in the heading puts it in the sidebar toc tree, which looks really weird.docs/README.md
to the.gitignore
because it should only be created/edited automatically during documentation generation and not actually committed to the repoSee local results: