Bapsflib style doc sidebar captions #777

StanczakDominik · 2020-03-31T18:38:27Z

WIP

I have added a changelog entry for this pull request (please see
changelog/README.rst for instructions, and if you need help with picking the PR type, ask!)
If adding new functionality, I have added (passing) tests and
docstrings. (Tests pop up at the bottom, in the checks box).
I have fixed any new failing tests (if you're unsure why
they're failing, ask!).

StanczakDominik · 2020-03-31T18:56:08Z

Version 1 https://5380-46810954-gh.circle-artifacts.com/0/docs/_build/html/index.html (last Development Guide -> About; my mistake)

StanczakDominik · 2020-03-31T19:22:45Z

Wait, since when do we have RTD builds in CI? 😱 :giddy-like-a-tired-CI-person:

codecov · 2020-03-31T19:23:01Z

Codecov Report

Merging #777 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #777   +/-   ##
=======================================
  Coverage   95.94%   95.94%           
=======================================
  Files          56       56           
  Lines        5000     5000           
=======================================
  Hits         4797     4797           
  Misses        203      203

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 34ddccc...5a336bd. Read the comment docs.

StanczakDominik · 2020-03-31T19:26:22Z

Okay, what I'd like you to compare is

the initial pure-sidebar cleanup on https://5380-46810954-gh.circle-artifacts.com/0/docs/_build/html/index.html
https://plasmapy--777.org.readthedocs.build/en/777/ (because WOW that RTD build is blazing fast!) or https://5385-46810954-gh.circle-artifacts.com/0/docs/_build/html/index.html with a cleaned up index page, so we don't duplicate the links on the left. After all, There should be one-- and preferably only one --obvious way to do it. ;)

namurphy

Thank you for working on this! I really like the direction this is going. I have a few suggestions, some of which I remember @rocco8773 saying in a side conversation a little while back.

We can probably skip spelling out the subpackage name/location in the sidebar (i.e., drop the plasmapy.formulary next to "Formulary")
We can probably skip saying "PlasmaPy" and "Plasma" for some of the items in the side bar since it can be a bit redundant. Like..."About PlasmaPy" could change to "About" and "Plasma Diagnostics" could change to "Diagnostics"
Could the sidebar headings for "Examples", "Development Guide", and "About" be changed to links to the relevent places so that the subitems can be removed?

rocco8773

I second what @namurphy said.

I do think the sidebar can still benefit from a little more organization and conciseness. Here's an organization I originally had in mind.

First Steps

Vision Statement (or an About)
Installing
Getting Started
[This would be a new page (i.e. one we don't already have). It would be a quick and dirty overview/guide to the package contents. It would explain the concept behind the top-level packages and any key classes. This would probably be a separate PR.]
Examples
How to Contribute (renaming of "Contributing to PlasmaPy")
Community Code of Conduct
Acknowledging & Citing

Package Features
[I'd say keep this pages alphabetized, versus some kind of importance priority.]

Diagnostics
Formulary
Particles
Particle Tracker (could be combined into the "Particles" page)
Plasma Objects
Utilities

Guide for Contributors

How to Contribute (this would link to the same page listed under "First Steps")
Community Code of Conduct (this would link to the same page listed under "First Steps")
Installing for Developers
Code Guidelines (or "Guide for Coding")
Test Guidelines (or "Guide for Testing")
Documentation Guidelines (or "Guide for Writing Documentation")
Release Guide (or "Guide for Releases")

All the Rest

Authors & Credits
Change Log
Stability of Subpackages
PlasmaPy.org (just link directly to our main page)

It would also be nice to add some kind of module index, much like the the indices the python documentation has in the upper right corner or bapsflib has under "package navigation". I know this is tricky though and might be better suited to a separate PR.

rocco8773

This is stating to like nice and clean! 🎉 It's already an improvement over what we originally had.

My only other general thought...Maybe we should reorder the docs/ folder to match the sidebar structure. We can keep the folders for the "Package Features" as they are (i.e. docs/diagnostics, docs/formulary, etc.), however, we can reshuffle the other pages into the folders docs/first_steps, docs/development_guide, and docs/all_the_rest.

docs/index.rst

Co-Authored-By: Erik Everson <[email protected]>

…PlasmaPy into Erik-style-doc-captions

It was just a TOC page, and the subpages are linked from elsewhere. It seems fine to dump it, since it's raising errors on CI about not being located in any TOC.

…ptions

StanczakDominik · 2020-04-15T06:50:00Z

Eh, future work for the docs directory reshuffling? I expect we'll be doing that soon-ish anyway.

rocco8773

This looks really nice to me!

We do have a mix of title styles in the sidebar, they switch back and forth between 'Feedback and Communication' and 'Feedback and communication'. We should be consistent with the style we use and I prefer 'Feedback and Communication'.

rocco8773 · 2020-04-15T19:01:45Z

Eh, future work for the docs directory reshuffling? I expect we'll be doing that soon-ish anyway.

I'm ok with leaving it to another PR, but we should make an issue as a reminder.

rocco8773 · 2020-04-16T16:42:57Z

This looks really nice to me!

We do have a mix of title styles in the sidebar, they switch back and forth between 'Feedback and Communication' and 'Feedback and communication'. We should be consistent with the style we use and I prefer 'Feedback and Communication'.

This style also needs to be applied to 'Plasma Tracker', 'Plasma Objects', and 'Package Utilities'.

namurphy

LGTM! I'm happy for it to be merged after the changes Erik suggested.

StanczakDominik · 2020-04-17T19:15:52Z

I feel like that could have easily been a code suggestion ;)

rocco8773 · 2020-04-17T21:13:54Z

I feel like that could have easily been a code suggestion ;)

Yeah, but I'm lazy. 😁

namurphy · 2020-04-17T21:20:37Z

Awesome! Thanks! This pull request makes me happy. 😸

Initial attempt

da81d3e

StanczakDominik force-pushed the Erik-style-doc-captions branch from fa77125 to da81d3e Compare March 31, 2020 18:49

StanczakDominik added 2 commits March 31, 2020 21:10

Minor text fixes to version 1

54b773c

Version 2 - cleanup

17096fa

StanczakDominik requested review from namurphy and rocco8773 March 31, 2020 19:26

namurphy requested changes Apr 2, 2020

View reviewed changes

rocco8773 reviewed Apr 3, 2020

View reviewed changes

StanczakDominik added 2 commits April 14, 2020 21:02

Add review fixes

9c80b6c

Add changelog entry

99b2edd

rocco8773 reviewed Apr 15, 2020

View reviewed changes

StanczakDominik and others added 3 commits April 15, 2020 08:17

Apply suggestions from code review

2387b1a

Co-Authored-By: Erik Everson <[email protected]>

Update docs/index.rst

ae18ec8

Co-Authored-By: Erik Everson <[email protected]>

Remove getting started page

aa83b31

StanczakDominik mentioned this pull request Apr 15, 2020

"Getting started" page in the docs #785

Open

StanczakDominik added 4 commits April 15, 2020 08:23

Remove code snippets in sidebar

da9b4ef

Merge branch 'Erik-style-doc-captions' of github.com:StanczakDominik/…

5067f46

…PlasmaPy into Erik-style-doc-captions

Remove about/index.rst

acabf75

It was just a TOC page, and the subpages are linked from elsewhere. It seems fine to dump it, since it's raising errors on CI about not being located in any TOC.

Merge remote-tracking branch 'upstream/master' into Erik-style-doc-ca…

2c8c007

…ptions

rocco8773 reviewed Apr 15, 2020

View reviewed changes

Communication

a75b79f

StanczakDominik mentioned this pull request Apr 16, 2020

Reshuffle docs directory #786

Open

StanczakDominik self-assigned this Apr 16, 2020

namurphy approved these changes Apr 17, 2020

View reviewed changes

Style

5a336bd

namurphy mentioned this pull request Apr 17, 2020

Update getting started for contributing docs #776

Closed

rocco8773 approved these changes Apr 17, 2020

View reviewed changes

rocco8773 merged commit 9e426f9 into PlasmaPy:master Apr 17, 2020

StanczakDominik deleted the Erik-style-doc-captions branch April 30, 2020 13:16

rocco8773 added the docs PlasmaPy Docs at http://docs.plasmapy.org label Jul 14, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bapsflib style doc sidebar captions #777

Bapsflib style doc sidebar captions #777

StanczakDominik commented Mar 31, 2020

StanczakDominik commented Mar 31, 2020 •

edited

Loading

StanczakDominik commented Mar 31, 2020

codecov bot commented Mar 31, 2020 •

edited

Loading

StanczakDominik commented Mar 31, 2020

namurphy left a comment

rocco8773 left a comment

rocco8773 left a comment

StanczakDominik commented Apr 15, 2020

rocco8773 left a comment

rocco8773 commented Apr 15, 2020

rocco8773 commented Apr 16, 2020

namurphy left a comment

StanczakDominik commented Apr 17, 2020

rocco8773 commented Apr 17, 2020

namurphy commented Apr 17, 2020

Bapsflib style doc sidebar captions #777

Bapsflib style doc sidebar captions #777

Conversation

StanczakDominik commented Mar 31, 2020

StanczakDominik commented Mar 31, 2020 • edited Loading

StanczakDominik commented Mar 31, 2020

codecov bot commented Mar 31, 2020 • edited Loading

Codecov Report

StanczakDominik commented Mar 31, 2020

namurphy left a comment

Choose a reason for hiding this comment

rocco8773 left a comment

Choose a reason for hiding this comment

rocco8773 left a comment

Choose a reason for hiding this comment

StanczakDominik commented Apr 15, 2020

rocco8773 left a comment

Choose a reason for hiding this comment

rocco8773 commented Apr 15, 2020

rocco8773 commented Apr 16, 2020

namurphy left a comment

Choose a reason for hiding this comment

StanczakDominik commented Apr 17, 2020

rocco8773 commented Apr 17, 2020

namurphy commented Apr 17, 2020

StanczakDominik commented Mar 31, 2020 •

edited

Loading

codecov bot commented Mar 31, 2020 •

edited

Loading