Remove dependency on m2r (use MyST instead) #6
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
No need for additional dependencies here, the License is anyway expected to be plain text.
NOTE: This breaks support for READMEs in rst format!
When using MyST to include Markdown-READMEs a different include command is needed in case of a README in rst format. Therefore move the code for searching and copying the README into a function and construct the include command there, depending on the format of the file. This is then added to the index.rst using a template variable. Move the equivalent code for the license file to its own function in the same way, to be consistent.
It is not used anymore.
|
@MaximilienNaveau Sorry, I forgot to add you as reviewer... |
MaximilienNaveau
approved these changes
Oct 11, 2022
| def _copy_readme(source_dir: Path, destination_dir: Path) -> str: | ||
| """Searches for a README in the source and copies it to the destination directory . | ||
|
|
||
| Searches for a "README.md" or "README.rst" (case-insensitive) in the source |
There was a problem hiding this comment.
We should also look for "README" and assume markdown
There was a problem hiding this comment.
Make sense but I think it will need a bit of rewrite. I'll create an issue to add this in a separate PR.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
We can use MyST to include the README.md into a rst file, thus getting rid of the dependency on m2r (which provides
mdincludethat was used before).As this makes different include commands necessary, depending on the format of the README ("md" or "rst"), move the code for handling the README to its own function and generate the appropriate include directive there. This is then added to index.rst using a template variable.
Apply equivalent changes for including the license file. Since the license is always expected to be plain text, no format distinction is needed here. Simply using standard
.. include::instead of.. mdinclude::results in the same output, at least for our BSD license files.Note that there is a minor difference to using m2r, the section headers of the included README are one level lower now (left is with m2r, right with MyST):
However, I don't think this is a problem. Apart from this the result looks exactly the same.
Closes #2.
How I Tested
By building the documentation for blmc_drivers (which has a README.md) and robot_fingers (which has README.rst).
I fulfilled the following requirements