Repository navigation
[Doc]: regularize doc formatting #26862
Description
Documentation Link
https://matplotlib.org/devdocs/devel/document.html#section-formatting
Problem
We acknowledge in our docs that we haven't completely moved our docs over to our specified format, which sometimes creates cascading effects when trying to combine/reorganize docs- directives like ..include don't like the mismatch and when reading the docs it can make it hard to figure out what level a given section is supposed to be at.
Suggested improvement
Reformat docs as needed so that they conform to the guidelines.
Use sentence case Upper lower for section titles, e.g., Possible hangups rather than Possible Hangups.
We aim to follow the recommendations from the Python documentation and the Sphinx reStructuredText documentation for section markup characters, i.e.:
# with overline, for parts. This is reserved for the main title in doc/index.rst. * with overline, for chapter. all pages except doc/index.rst should start with "chapter" or lower. =, for sections -, for subsections ^, for subsubsections ", for paragraphs
NOTES:
- do not sentence case files under "/project"
- ignore files in any "api_changes", "whats_new", or MEP file/folder.
- do not add new headings without a justification. This issue is about converting existing heading markers into its corresponding heading markers in the list above.
Documents with old style formatting:
This work is mostly converting ~~ to ^^^
Please post here which file you are working on:
project
API
contribute
- devel/contribute DOC: made "open PR on MPL" a section in contribute guide #26961
- devel/document DOC: separate and clarify axisartist default tables #26754
- devel/release_guide Update developer release guide to follow conventions #27118
- Formatted release note docs #27039
user_guide
- user_guide/artists/artist_intro updated artist_intro.rst #27036
- user_guide/figure/api_interfaces updated api_interfaces.rst #27043
- user_guide/figure/interactive updated interactive.rst #27054
text
- user_guide/text/text_intro make fonts.py, mathtext.py, text_intro.py confirm to docs guidelines #27096
- user_guide/text/fonts make fonts.py, mathtext.py, text_intro.py confirm to docs guidelines #27096
- user_guide/text/mathtext make fonts.py, mathtext.py, text_intro.py confirm to docs guidelines #27096
toolkits
- user_guide/toolkits/axes_grid Reformatted documentation under toolkits and tutorials directory #26985
Activity
github-actions commentedon Sep 21, 2023
Good first issue - notes for new contributors
This issue is suited to new contributors because it does not require understanding of the Matplotlib internals. To get started, please see our contributing guide.
We do not assign issues. Check the Development section in the sidebar for linked pull requests (PRs). If there are none, feel free to start working on it. If there is an open PR, please collaborate on the work by reviewing it rather than duplicating it in a competing PR.
If something is unclear, please reach out on any of our communication channels.
AnviVerma27 commentedon Oct 3, 2023
can I work on this?
story645 commentedon Oct 3, 2023
I think @iamfaham is working on some parts of this, so I'd recommend working on the parts they're not working on. @iamfaham are you still working on this and if so which pages?
15IITian commentedon Oct 3, 2023
Thank you for your response @story645
Actually when I read for first time , I thought that it should be made sub-section of
Draw first plot.But if my work is not on right path , then please clarify/guide me .
15IITian commentedon Oct 3, 2023
Thank you for your response @jklymak
I understand organization's concerns .
Being new to open source , I thought to make smaller PR's in order to get comfortable with open-source & matplotlib .
Thus , there was no intention to increase my PR's no in hactoberfest ;)
I will keep this in mind now onwards .
story645 commentedon Oct 3, 2023
I updated the PR description with a list of files that use old style formatting. Please work on files that are unclaimed.
iamfaham commentedon Oct 3, 2023
I am working on the user_guide/toolkits/axes_grid file.
iamfaham commentedon Oct 3, 2023
Hey @story645 , I have created a PR in which i have updated 2 of the necessary docs. Let me know of any necessary changes to the same.
AnviVerma27 commentedon Oct 4, 2023
i will be working on this user/project/citing
gargmonika commentedon Oct 5, 2023
Hey, I will be working on api/animation file.
BS14 commentedon Oct 7, 2023
Hey, I will be working on user_guide/artists/artist_intro
Ruchir0403 commentedon Oct 8, 2023
Can I work on this?
story645 commentedon Oct 9, 2023
@Ruchir0403 sure, you can work on whatever isn't currently being worked on
5 remaining items
story645 commentedon Oct 17, 2023
Sure for release guide, give @gargmonika a bit to reply on if they're still planning on working on animation
gargmonika commentedon Oct 17, 2023
Hey @story645 thanks for giving me chance. I really apologize i was really occupied with my full time work lately. I would surely still like to work on this . But if its under high priority and someone is available immediately, i don't mind
to pass it on.
story645 commentedon Oct 17, 2023
It's not high priority, but we'll have other issues of similar level & scope coming up if now is not a good time for you to work on this.
Disha-Baghel commentedon Oct 27, 2023
May I contribute to unresolved tasks if someone isn't addressing their assigned issues?
story645 commentedon Oct 27, 2023
You're welcome to work on animation and give @aseriesof-tubes a few days to indicate whether they're still planning to work on things?
aseriesof-tubes commentedon Oct 27, 2023
Hi @Disha-Baghel and @story645, I'll be done with them shortly :)
story645 commentedon Nov 2, 2023
Thanks folks, the ones listed here are done so I'll close this! There are probably still files around but we'll do that intentionally more as a "while changing docs"
QuLogic commentedon Nov 2, 2023
api/animation is not done yet?
story645 commentedon Nov 2, 2023
Ack, confused it w/ the api_interfaces! :/
raghuramsirigiri commentedon Nov 19, 2023
Can I work on api/animation? I want to start my open source contribution journey with this.
story645 commentedon Nov 19, 2023
Sure