Review 2 (reviews open): Add: documentation section to package guide #19

lwasser · 2022-12-29T18:22:09Z

This pr builds on top of #14 which will be closed. It contains a lot of new and re-organized information based upon feedback.

I would like feedback by January 16 (which is a holiday in the US). I will hope to MERGE this pr that week by Jan 18th.

Update documentation/contributing-file.md Co-authored-by: Alexandre Batisse <[email protected]> Update documentation/index.md Co-authored-by: Alexandre Batisse <[email protected]> Update documentation/index.md Co-authored-by: Alexandre Batisse <[email protected]> Update documentation/package-documentation-sphinx.md Co-authored-by: Alexandre Batisse <[email protected]> Update documentation/readme-file-best-practices.md Co-authored-by: Alexandre Batisse <[email protected]> Update documentation/readme-file-best-practices.md Co-authored-by: Alexandre Batisse <[email protected]> Update documentation/readme-file-best-practices.md Co-authored-by: Alexandre Batisse <[email protected]> Update documentation/readme-file-best-practices.md Co-authored-by: Alexandre Batisse <[email protected]> Update documentation/readme-file-best-practices.md Co-authored-by: Alexandre Batisse <[email protected]>

Update documentation/index.md Co-authored-by: Ariane Sasso <[email protected]> Update documentation/package-documentation-sphinx.md Co-authored-by: Ariane Sasso <[email protected]>

Co-authored-by: David Nicholson <[email protected]> Update documentation/package-documentation-sphinx.md Co-authored-by: David Nicholson <[email protected]>

… left bar links

tupui

Great write up! I have a few suggestions if I may 😃

documentation/contributing-license-coc.md

documentation/package-documentation-best-practices.md

documentation/python-package-documentation-tools.md

tupui · 2023-01-02T16:02:31Z

documentation/readme-file-best-practices.md

+
+Your README file should have the following information: 
+- [ ] The name of the package
+- [ ] Badges for the packages current published version, documentation and test suite build. (OPTIONAL: test coverage) 


Personal take, I don't like badges about CI because it does not represent what users would get. Most users would get a stable release, hence this has little value. I even think that it can send a wrong message to some people if they see a red badge for some time. Depending on the CI jobs, that does not necessarily mean the project is broken all the time.

documentation/readme-file-best-practices.md

documentation/website-hosting-optimizing-your-docs.md

lwasser · 2023-01-04T22:48:43Z

documentation/python-package-documentation-tools.md

@@ -0,0 +1,251 @@
+# Python Package Documentation


NOTE: could be worth revisiting this and adding nbgallery as a front end with nbsphinx - will provide a much nicer front end for peope to use https://nbsphinx.readthedocs.io/en/0.8.11/subdir/gallery.html thanks to @astrojuanlu for the tip!

TODO: this is a really important item but i'm going to add this as an issue #35 so we can circle back and work on it given the size if this pr currently is massive

NickleDave

Huge step forward for our docs docs 🙂

This review was spread out over three days, I promise I did try to remove any of the extra grumpiness from late-night reviewing. Hope that it's helpful

documentation/index.md

documentation/contributing-license-coc.md

documentation/website-hosting-optimizing-your-docs.md

index.md

documentation/website-hosting-optimizing-your-docs.md

NickleDave

Huge step forward for our docs docs 🙂

This review was spread out over three days, I promise I did try to remove any of the extra grumpiness from late-night reviewing. Hope that it's helpful

lwasser · 2023-01-09T17:41:30Z

@all-contributors please add @tupui for doc, design

allcontributors · 2023-01-09T17:41:56Z

@lwasser

I've put up a pull request to add @tupui! 🎉

tupui · 2023-01-09T17:56:00Z

Thanks 😊

documentation/index.md

Co-authored-by: Pamphile Roy <[email protected]>

sneakers-the-rat · 2023-01-09T18:15:41Z

One thought on TOC/document structure:

might be nice to group some things together and break up some of the pages for skimming/reference?

|- Overview
|- Write the Docs
|  |- Basic Sections
|  |- Examples/Tutorials
|  |- API Docs
|- Repo Files
|  |- README.md
|  |- LICENSE.txt
|  |- CONTRIBUTING.md
|  |- CODE_OF_CONDUCT.md
|- Documentation Tools
|  |- Sphinx
|  |- Sphinx Extensions
|- Hosting
|  |- ReadTheDocs
|  |- SEO

sneakers-the-rat

I like :) thanks for all your work writing this. Hopefully these are useful, sorry if they are all very persnickety, thus is the nature of feedback.

My big global comment is that some macro-level reorganization would be nice: as is the order feels a little random and I am not left with a clear picture of what is required by pyOpenSci re: documentation since it's buried around on a few pages. I see that several files were removed and combined here, and so not sure what the deal is there but I suggested a simple 2-layer nested structure in one of my comments that I feel like would be helpful to keep the docs expandable and also be able to navigate around for someone interested in submitting.

thanks again :) all my comments 'optional' to take or leave as they're useful or not.

documentation/package-documentation-best-practices.md

sneakers-the-rat · 2023-01-09T18:22:14Z

documentation/package-documentation-best-practices.md

+## Documentation landing page best practices 
+
+To make it easy for users to find what they need quickly, all packages should 
+have 4 elements on the home page of their documentation:


I get a little confused here at the order - above docs are described as having two (2.5 with tutorials) parts, then here it seems like now we are saying docs have 4 parts and then restates the two parts. maybe unify this into a single statement of docs structure and then say "landing page should link out to all top-level things in the basic structure."

i totally understand why. I suspect the new organization will be more clear. I tried to clarify the sections... but let me know what you think.

oh and also this is just a suggest for design of package landing page. i added an image below it. (From geopandas)

documentation/package-documentation-best-practices.md

sneakers-the-rat · 2023-01-09T18:28:29Z

documentation/package-documentation-best-practices.md

+    Return
+    ------
+    extent_json: A GeoJSON style dictionary of corner coordinates
+    for the extent


creates an additional bullet point in the return list (see image below this)

@sneakers-the-rat i don't understand this comment and what image you are referring to. what are you referring to ? do you mean in the return when you run help()?

sneakers-the-rat · 2023-01-09T18:28:34Z

documentation/package-documentation-best-practices.md

+
+```
+
+```{figure} ../images/sphinx-rendering-extent-to-json-earthpy.png


might as well just write a dummy function and call autodoc on it (and then show the autodoc directive as well?) and show the generated docs from the docstring? might be easier to maintain than having to eg. update the screenshot if something changes.

i could this is from earthpy i could pull from docs and such - we did run doctest ... let me look at this.

oh i think i see what you're saying. i no longer maintain earthpy. we could add this to our examplePy package repo... not in this PR but it's a good idea for the future. then we have full control and can use it for doc updates. i'll make a note of this

sneakers-the-rat · 2023-01-09T19:00:09Z

documentation/contributing-license-coc.md

+* A CODE_OF_CONDUCT.md file 
+* A development guide (if possible)
+
+## What a CONTRIBUTING.md file should contain


Same thing with each of these headings

Contributing
License
Code of Conduct

documentation/contributing-license-coc.md

sneakers-the-rat · 2023-01-09T19:02:41Z

documentation/contributing-license-coc.md

+* A link to licensing information found in your README file. 
+* A link to a development guide if you have one
+
+## What the development guide for your Python package should contain 


Not clear how this is different than the Contributing.md and makes me feel like i'm supposed to write another guide. I would make this a subheading underneath contributing and shorten the header to Developer Docs or something

oh it is another guide! the community seems to be moving away from contributing and development being conflated. So contributing guides are more about understanding what types of contributions are welcome - issues, pull requests, questions, and how to submit them. Whereas a dev guide describes the dev workflow - fewer contributors will install pre-commit hooks and want to know about build tools. but that should be documented.

this is particularly important if you want to onboard a new contributor OR for pyOpenSci if a maintainer steps down and we need to find someone new - we want the workflow documented.

this page tho is also split out as we discussed so i hope the entire section is clearer. pyopensci does NOT require a dev guide but i think it will be important when we need to find new maintainers for packages.

sneakers-the-rat · 2023-01-09T19:04:24Z

documentation/contributing-license-coc.md

+software license that is approved 
+by the Open Software Initiative (OSI). OSI's website has a 
+[list of popular licenses](https://opensource.org/licenses). GitHub also has a 
+[handy tool](https://choosealicense.com/) for choosing a license. 


Linking to the tool is great. Maybe broad strokes description of the basic "big cuts" differences in licenses and perhaps a recommendation or a statement about which licenses are most common/expected by pyOpenSci

@sneakers-the-rat are you open to writing a bit more about licenses and COC directly via a pr? we could either add it here OR we could add it once this is merged. When i push my latest revisions up this PR is going to get messy but id' welcome your making direct content additions to it or in a new pr when this is merged.

sure! of course. lmk when it's in a more settled state to add to

awesome! i'm about to push a really big set of fixes. and then however you want to contribute you are welcome to. You could either submit a PR on top of this pr? Or you can add inline changes here ! however you'd like to do this i'm open . I now have a coc page and a license page. (I may be missing sufficient information around citation.)

sneakers-the-rat · 2023-01-09T19:05:01Z

documentation/contributing-license-coc.md

+
+If you choose your license through GitHub, you can also automatically get a copy of the license file to add to your repository.
+
+## The CODE_OF_CONDUCT.md file


a lil more on what the code of conduct should do/what is typically in them would also be nice.

i wasn't sure what to add on this page. Right now i have contributing and COC as one page because they are both short sections. Maybe we can pull this out as an issue as well and add more to it once this PR is merged? i appreciate this feedback .

created an issue here #37 that we can then circle back on - great suggestion!

Co-authored-by: David Nicholson <[email protected]>

lwasser · 2023-01-09T20:30:00Z

@all-contributors please add @sneakers-the-rat for code, design

allcontributors · 2023-01-09T20:30:10Z

@lwasser

I've put up a pull request to add @sneakers-the-rat! 🎉

lwasser · 2023-01-10T18:55:42Z

I like :) thanks for all your work writing this. Hopefully these are useful, sorry if they are all very persnickety, thus is the nature of feedback.

My big global comment is that some macro-level reorganization would be nice: as is the order feels a little random and I am not left with a clear picture of what is required by pyOpenSci re: documentation since it's buried around on a few pages. I see that several files were removed and combined here, and so not sure what the deal is there but I suggested a simple 2-layer nested structure in one of my comments that I feel like would be helpful to keep the docs expandable and also be able to navigate around for someone interested in submitting.

thanks again :) all my comments 'optional' to take or leave as they're useful or not.

@sneakers-the-rat i really appreciate your thoughts on this and the suggested reorg. it's much cleaner now. i think i was stuck working in an old structure but also trying to move a lot of content across into a new format. i needed your fresh eyes to reconsider organization. THANK YOU for the huge contribution here. i am SO SO SO appreciative.

lwasser · 2023-01-10T19:02:48Z

ok y'all. i've gotten through MANY of the comments.
Tomorrow (well if jury duty doesn't consume my day) i'll work through the rest. The current state of this PR is that the entire flow has been improved and updated. so i had to manually update many of the small syntax fixes. it's possible i missed some but i did my very best to get everything!

lwasser · 2023-01-10T19:03:54Z

I think the last BIG picture comment that i don't feel confident on is how we make it clear what pyos REQUIRES vs just guidance and best practices following @sneakers-the-rat comments. as such i'll open an issue about that as well.

lwasser · 2023-01-19T16:55:03Z

ok yall. i am going to MERGE this PR. we've i think had well over 400 comments and contributions here from various folks and i appreciate it all. I will merge but please know this is a LIVING document. it is not the final - this is just round 1. ok round 2 for this content. We will merge and then update / fix enhance as we go. Thank you all for being a part of this vision and for supporting this effort! ✨

lwasser and others added 11 commits November 30, 2022 11:24

ADD: documentation section to guide

8370452

Fix: Review edits from @lwasser and @arianesasso

f0e1a3c

Fix: add docstring examples

d409543

Fix: review edits to documentation from @arianesasso

ec2d032

Update documentation/index.md Co-authored-by: Ariane Sasso <[email protected]> Update documentation/package-documentation-sphinx.md Co-authored-by: Ariane Sasso <[email protected]>

Fix: Review edits to doc section from @NickleDave

8ced667

Co-authored-by: David Nicholson <[email protected]> Update documentation/package-documentation-sphinx.md Co-authored-by: David Nicholson <[email protected]>

Fix: edits to doc section from @SimonMolinsky

8cc1bc3

rebase

dfea3b3

Fix: numerous cleanup edits to contributing and readme files

38fad88

Fix: breakout docs into separate pages with separate goals and update…

70410f5

… left bar links

Fix: add tutorial and coc text and general cleanup

8107341

tupui reviewed Jan 2, 2023

View reviewed changes

lwasser commented Jan 4, 2023

View reviewed changes

lwasser added the 🚀 ready-for-review label Jan 5, 2023

NickleDave suggested changes Jan 7, 2023

View reviewed changes

allcontributors bot mentioned this pull request Jan 9, 2023

docs: add tupui as a contributor for doc, and design #31

Merged

sneakers-the-rat reviewed Jan 9, 2023

View reviewed changes

documentation/index.md Outdated Show resolved Hide resolved

lwasser and others added 3 commits January 9, 2023 11:11

Update documentation/package-documentation-best-practices.md

0c28fd5

Co-authored-by: Pamphile Roy <[email protected]>

Update documentation/package-documentation-best-practices.md

a2b31e3

Co-authored-by: Pamphile Roy <[email protected]>

Fix: addressing changes from @tupui

179246d

lwasser added 2 commits January 9, 2023 11:19

Fix: add text to example in docstring and spaces review- @tupui

a696b89

Fix: update docstring with example text @tupui

144eefd

sneakers-the-rat reviewed Jan 9, 2023

View reviewed changes

lwasser and others added 2 commits January 9, 2023 13:01

Update documentation/index.md

116231c

Co-authored-by: David Nicholson <[email protected]>

Update documentation/website-hosting-optimizing-your-docs.md

1004cb4

Co-authored-by: David Nicholson <[email protected]>

lwasser and others added 3 commits January 9, 2023 13:11

Update documentation/website-hosting-optimizing-your-docs.md

044689f

Co-authored-by: David Nicholson <[email protected]>

Fix: feedback from @tupui, @NickleDave

22a5f4a

Update documentation/website-hosting-optimizing-your-docs.md

444eae3

Co-authored-by: David Nicholson <[email protected]>

allcontributors bot mentioned this pull request Jan 9, 2023

docs: add sneakers-the-rat as a contributor for code, and design #33

Merged

This was referenced Jan 10, 2023

Add: type hints to docstring examples and a paragraph on what type hints are #36

Closed

Python Package Guide: Update text - Further flesh out what belongs in a code of conduct page in our package guide #37

Closed

lwasser added 2 commits January 9, 2023 18:45

Fix: Major reorganization following comments from @sneakers-the-rat

7e2e059

Fix: massive update to the structure of the docs section

fec16a5

lwasser mentioned this pull request Jan 10, 2023

Licensing for package CODE vs documentation (text, tutorials) #39

Open

Fix: responded to the 100+ comments left on this pr - phew

b78fc4f

lwasser mentioned this pull request Jan 10, 2023

Cross linking between author checks in our peer review guide and guidance in the packaging guide #42

Open

lwasser added 2 commits January 10, 2023 14:49

Fix: more fixes from @sneakers-the-rat review and @NickleDave review

d73db2f

Fix: final cleanup of sections and removal of peer review checks

cccb65d

lwasser merged commit 710cb91 into pyOpenSci:main Jan 19, 2023

lwasser mentioned this pull request Jan 19, 2023

REVIEW 1 (reviews closed) - ADD: Documentation section to our packaging guide #14

Closed


		```

		```{figure} ../images/sphinx-rendering-extent-to-json-earthpy.png


		If you choose your license through GitHub, you can also automatically get a copy of the license file to add to your repository.

		## The CODE_OF_CONDUCT.md file

Review 2 (reviews open): Add: documentation section to package guide #19

Review 2 (reviews open): Add: documentation section to package guide #19

Conversation

lwasser commented Dec 29, 2022 • edited Loading

tupui left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NickleDave left a comment

Choose a reason for hiding this comment

NickleDave left a comment

Choose a reason for hiding this comment

lwasser commented Jan 9, 2023

allcontributors bot commented Jan 9, 2023

tupui commented Jan 9, 2023

sneakers-the-rat commented Jan 9, 2023

sneakers-the-rat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lwasser commented Jan 9, 2023

allcontributors bot commented Jan 9, 2023

lwasser commented Jan 10, 2023

lwasser commented Jan 10, 2023

lwasser commented Jan 10, 2023

lwasser commented Jan 19, 2023

lwasser commented Dec 29, 2022 •

edited

Loading