8000 Clarify "Helping with Documentation" by csabella · Pull Request #335 · python/devguide · GitHub
[go: up one dir, main page]
Skip to content

Clarify "Helping with Do 8000 cumentation" #335

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
Merged
merged 4 commits into from
Mar 19, 2018
Merged

Clarify "Helping with Documentation" #335

merged 4 commits into from
Mar 19, 2018
+9 −4

Conversation

csabella
Copy link
Contributor
@csabella csabella commented Mar 6, 2018

For issue #334 .

I've made a few changes in this PR to maybe make building the Python docs clearer.

  • Added a section heading on "Helping with Documentation"
  • Added parenthetical text to "Helping with the Dev Guide" section so the reader realizes that it's talking about a different set of docs.
  • Moved the 'Building the documentation" section of the "Documenting Python" page from the end to right after the introduction. I think it's more 'findable' this way.
  • Add a short introduction to the 'Building the Documentation' section.

I hope these changes don't step on decisions made in the past, but I think they might help a newcomer navigate more easily.

brettcannon
brettcannon requested changes Mar 6, 2018
View reviewed changes
Copy link
Member
@brettcannon brettcannon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One tweak to make to new stuff, and if you want to fix up other stuff while you're here I left comments on that as well.

docquality.rst Outdated
The Developer's Guide (what you're reading now) uses the same process as the
main Python documentation, except for some small differences. The source
lives in a `separate repository`_ and bug reports should be submitted to
the `the GitHub tracker`_.
Copy link
Member
@brettcannon brettcannon Mar 6, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"its GitHub tracker_` (basically helping differentiate which GitHub issue tracker you're talking about and dropping the double "the").

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"its"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops. 😄 Updated my comment according to Ned's catch of my grammatical mistake.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

documenting.rst Outdated

The toolset used to build the docs is written in Python and is called Sphinx_.
Sphinx is maintained separately and is not included in this tree. Also needed
are docutils_, supplying the base markup that Sphinx uses; Jinja_, a templating
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docutils is a dependency for Sphinx so I don't think it's worth explaining this much detail (especially if Sphinx ever changes what it depends on).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deferred to a separate PR.

documenting.rst Outdated
engine; and optionally Pygments_, a code highlighter.

You are expected to have installed the latest stable version of
Sphinx_ and blurb_ on your system or in a virtualenv_ (which can be
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically it's a "virtual environment" because virtualenv is the name of the project that introduced the concept of virtual environments.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deferred to a separate PR.

@ned-deily
Copy link
Member

Note also this conflicts with the changes proposed in PR #327, i.e. to remove the "without make" section.

willingc
willingc reviewed Mar 10, 2018
View reviewed changes
Copy link
Collaborator
@willingc willingc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @csabella, Thanks for the pull request and your ongoing contributions. I appreciate them 👍

Perhaps it would be good to split this PR into two. One for the docquality file and one for the documenting file. I suggest that since the building section has another open PR and there are likely to be multiple opinions on the content. This way we can merge the first PR in a timely manner while we work through the building steps which may take a bit longer to sort out the docs.

If you need any help splitting the PR let me know and I would be happy to do coach you through it.

@csabella
Copy link
Contributor Author

Thank you all for the reviews and I apologize for the delay in getting back to this. As per Carol's suggestion, I've reverted the changes on documenting.rst to focus this change on making the docquality.rst page clearer for beginners. The change on documenting.rst was really just to feature the build section more prominently and that (as well as incorporating Brett's suggestions for cleaning it up) can certainly happen after the other PR is merged.

Thanks!

willingc
willingc reviewed Mar 12, 2018
View reviewed changes
Copy link
Collaborator
@willingc willingc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One small edit needed and this looks good to me.

docquality.rst Outdated
The Developer's Guide (what you're reading now) uses the same process as the
main Python documentation, except for some small differences. The source
lives in a `separate repository`_ and bug reports should be submitted to
the `its GitHub tracker`_.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One small correction still needed after the PR split the. Thanks @csabella 👍

willingc
willingc approved these changes Mar 12, 2018
View reviewed changes
Copy link
Collaborator
@willingc willingc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@willingc willingc merged commit 0ef5fe6 into python:master Mar 19, 2018
@willingc
Copy link
Collaborator

@brettcannon I'm going to merge @csabella's PR. I believe that she addressed your concerns.

Thanks @csabella ☀️

@willingc willingc mentioned this pull request Mar 19, 2018
Closed
AA-Turner pushed a commit to AA-Turner/devguide that referenced this pull request Jun 17, 2022
@csabella @willingc
Clarify "Helping with Documentation" (python#335)
bab4578 
* Clarify "Helping with Documentation"

* Suggested changes.

* Suggested changes.

* Remove extra "the"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@brettcannon brettcannon brettcannon requested changes

@ned-deily ned-deily ned-deily left review comments

@willingc willingc willingc approved these changes

Assignees
No one assigned
Labels
CLA signed
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@csabella @ned-deily @willingc @brettcannon @the-knights-who-say-ni
0