Skip to content

[Doc]: regularize doc formatting #26862

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.

Sign up for GitHub

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

Jump to bottom
Closed
16 tasks done
story645 opened this issue Sep 21, 2023 · 29 comments
Closed
16 tasks done

[Doc]: regularize doc formatting #26862

story645 opened this issue Sep 21, 2023 · 29 comments
Labels
Documentation Good first issue Open a pull request against these issues if there are no active ones!
Milestone
v3.8-doc

Comments

@story645
Copy link
Member

story645 commented Sep 21, 2023 •
edited
Loading

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

user_guide

text
toolkits

tutorials

gallery
@story645 story645 added Documentation Good first issue Open a pull request against these issues if there are no active ones! labels Sep 21, 2023
@github-actions
Copy link

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.

@iamfaham iamfaham mentioned this issue Sep 29, 2023
Closed
2 tasks
@AnviVerma27
Copy link
Contributor

can I work on this?

@story645
Copy link
Member Author

story645 commented 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 15IITian mentioned this issue Oct 3, 2023
Closed
@15IITian
Copy link

15IITian commented 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
Copy link

15IITian commented 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
Copy link
Member Author

story645 commented Oct 3, 2023 •
edited
Loading

I updated the PR description with a list of files that use old style formatting. Please work on files that are unclaimed.

@iamfaham
Copy link
Contributor

iamfaham commented Oct 3, 2023

I am working on the user_guide/toolkits/axes_grid file.

@iamfaham iamfaham mentioned this issue Oct 3, 2023
Merged
2 tasks
@iamfaham
Copy link
Contributor

iamfaham commented 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
Copy link
Contributor

i will be working on this user/project/citing

@AnviVerma27 AnviVerma27 mentioned this issue Oct 4, 2023
Merged
5 tasks
@gargmonika
Copy link

Hey, I will be working on api/animation file.

@BS14
Copy link

BS14 commented Oct 7, 2023

Hey, I will be working on user_guide/artists/artist_intro

@Ruchir0403
Copy link

Can I work on this?

@story645
Copy link
Member Author

story645 commented Oct 9, 2023

@Ruchir0403 sure, you can work on whatever isn't currently being worked on

@BS14 BS14 mentioned this issue Oct 9, 2023
Merged
5 tasks
@BS14
Copy link

BS14 commented Oct 9, 2023

Hey, I will be working on user_guide/figure/api_interfaces and user_guide/figure/interactive

@story645 story645 mentioned this issue Oct 9, 2023
Merged
5 tasks
This was referenced Oct 10, 2023
Merged
Merged
@Prince-Vijay-Santhosh
Copy link

Prince-Vijay-Santhosh commented Oct 14, 2023 •
edited
Loading

I would like to work on this issue.

@story645
Copy link
Member Author

Sure which thing?

@adescoeudres adescoeudres mentioned this issue Oct 15, 2023
Merged
1 task
@aseriesof-tubes
Copy link

Hi! I'll be working on examples/subplots_axes_and_figures and examples/text_labels_and_annotations/angle_annotation.

@0taj
Copy link
Contributor

0taj commented Oct 17, 2023

Hello, I'll work on devel/release_guide and api/animation

@story645
Copy link
Member Author

Sure for release guide, give @gargmonika a bit to reply on if they're still planning on working on animation

@gargmonika
Copy link

Sure for release guide, give @gargmonika a bit to reply on if they're still planning on working on animation

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.

@0taj 0taj mentioned this issue Oct 17, 2023
Merged
2 tasks
@story645
Copy link
Member Author

But if its under high priority and someone is available immediately, i don't mind to pass it on.

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
Copy link

May I contribute to unresolved tasks if someone isn't addressing their assigned issues?

@story645
Copy link
Member Author

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
Copy link

Hi @Disha-Baghel and @story645, I'll be done with them shortly :)

@aseriesof-tubes aseriesof-tubes mentioned this issue Oct 27, 2023
Merged
5 tasks
@melissawm melissawm mentioned this issue Oct 28, 2023
Merged
5 tasks
@story645
Copy link
Member Author

story645 commented 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"

@story645 story645 closed this as completed Nov 2, 2023
@QuLogic
Copy link
Member

QuLogic commented Nov 2, 2023

api/animation is not done yet?

@story645
Copy link
Member Author

story645 commented Nov 2, 2023

Ack, confused it w/ the api_interfaces! :/

@story645 story645 reopened this Nov 2, 2023
@raghuramsirigiri
Copy link
Contributor

Can I work on api/animation? I want to start my open source contribution journey with this.

@story645
Copy link
Member Author

Sure

@raghuramsirigiri raghuramsirigiri mentioned this issue Nov 20, 2023
Merged
3 tasks
@QuLogic QuLogic added this to the v3.8-doc milestone Nov 21, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Good first issue Open a pull request against these issues if there are no active ones!
Projects
None yet
Milestone
v3.8-doc
Development

Successfully merging a pull request may close this issue.

Reformatted documentation under project directory iamfaham/matplotlib