-
Notifications
You must be signed in to change notification settings - Fork 844
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
Fix code formatting in docstrings for a few functions #6848
base: master
Are you sure you want to change the base?
Fix code formatting in docstrings for a few functions #6848
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.
I think the changes to your docs make them considerably less useful.
As is, you can copy examples from the doc string and paste them directly jnto code.
After this change you'd have to edit out the prompts.
I believe that the prompts are almost only useful when they are present as part of doctests: showing both input and output
In their current state, the code blocks in that documentation page are not presented as code blocks, but as run-on paragraphs: I proposed using are formatted with
And as shown in the documentation screenshot above, when you select the code with the mouse the If the preference is to format code blocks that are not doctest-like (showing both input and output) without using P.S. In the code block above, GitHub adds a Copy button which we might also want to add to the RDKit documentation to facilitate copying blocks of code. I believe the sphinx-copybutton extension achieves that. I can take that on if it's something we want to add. |
The solution to this is apparently to end the line above with two colons: https://stackoverflow.com/a/64452858 I tested this with a couple of doc strings and that seems to work. |
Thanks for researching that. I'll try using two colons, ideally after Documentation preview builds on CI #6849 is in place so I can check that I formatted the code blocks correctly--an easy mistake to make is to format a first code block correctly but not a second code block, for example in ExplainPairScore. |
Reference Issue
What does this implement/fix? Explain your changes.
Format code in docstrings as code blocks by adding
>>>
before lines of codeAny other comments?
I noticed this issue in the documentation for the MolsMatrixToGridImage code I submitted (scroll down to EXAMPLES), then discovered that other docstrings had similar issues, so I addressed the couple that I found.