Embed README in index.rst #65
Conversation
There was a problem hiding this comment.
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.
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.
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.
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.
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.
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.
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.mdREADME.mdindocs/index.rstby copyingCUPiD/README.mdinto the docs directory indocs/conf.pyand 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.mdto the.gitignorebecause it should only be created/edited automatically during documentation generation and not actually committed to the repoSee local results:
