Skip to content
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

Various improvements/updates to the documentation #875

Merged
merged 20 commits into from
Jul 26, 2020
Merged

Various improvements/updates to the documentation #875

merged 20 commits into from
Jul 26, 2020

Conversation

rocco8773
Copy link
Member

@rocco8773 rocco8773 commented Jul 26, 2020 •
edited
Loading

I originally started this PR to fix #874 and, as always, I went down the rabbit hole. When will I learn!!

Improvement/Updates made in this PR...

  1. Replace the "home" text/image in the RTD sidebar with the plasmapy logo. (see pic below)
  2. Use the datatime package to define the copyright years in the copyright configuration variable (in conf.py). One less thing to maintain!!!
  3. Make it so :hidden: toctree's do NOT show up in the navigation sidebar.
  4. Un-hide all toctree directives in ./docs/index.rst. This make the toctree's visible on the landing page and in the sidebar.
  5. Replace the "html nbgallery" on the landing page with a real nbgallery that is marked :hidden: (fixes Thumbnails missing/broken on plasmapy documentation webpage home #874). nbgallery behaves a little differently than toctree in that the gallery itself is not hidden when marked with :hidden: but it is still hidden from the sidebar. Another thing we do not have to manually maintain!!
  6. Add a custom CSS stylesheet. This is used in this PR to...
    1. Re-style toctree directives when used in a table.
    2. Create styles for adding the module and index navigation links to the sidebar.
  7. Add navigation links modules and index to the sidebar "header". (see pic below)
  8. Move the link to view page source code from the header of the page to the footer of the page.
  9. Add to the foot a link to jump back to the top of the page.

image

Closes #874

@rocco8773 rocco8773 added the docs PlasmaPy Docs at http://docs.plasmapy.org label Jul 26, 2020
@rocco8773 rocco8773 self-assigned this Jul 26, 2020
@codecov
Copy link

codecov bot commented Jul 26, 2020 •
edited
Loading

Codecov Report

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

Impacted file tree graph

@@           Coverage Diff           @@
##           master     #875   +/-   ##
=======================================
  Coverage   96.13%   96.13%           
=======================================
  Files          60       60           
  Lines        5309     5309           
=======================================
  Hits         5104     5104           
  Misses        205      205

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 0997e67...ec0e100. Read the comment docs.

rocco8773 added 13 commits July 25, 2020 20:38
@rocco8773
make it so :hidden: toctree's do not show up in the sidebar
83b86c9
@rocco8773
unhide toctree's
6577176
@rocco8773
replace the html nbgallery with a real nbgallery marked with :hidden:
1e2da1c
@rocco8773
define html_static_path
028b7aa
@rocco8773
create a CSS stylesheet to override elements of the RTD CSS...add ove…
a2045dc 
…rrides for a toctree in a table
@rocco8773
add the CSS override stylesheet to sphinx
847354c
@rocco8773
move toctree directives into the table on ./docs/formulary/index.rst …
30dff62 
…and remove the hidden toctree
@rocco8773
define a common prefix for modindex generation
b6fc22b
@rocco8773
CSS style for module and index links in the sidebar
1851712
@rocco8773
create layout.html template that places the module and index links …
6bf6250 
…in the sidebar
@rocco8773
remove the module, index, and search links from the landing page ./do…
355f114 
…cs/index.rst
@rocco8773
create links in the page footer to view page source code and jump to …
914eebc 
…the top of the page
@rocco8773
remove link to view page source code from the header of the page
97c377e
@rocco8773 rocco8773 marked this pull request as ready for review July 26, 2020 04:24
@StanczakDominik
Copy link
Member

Oh wow.

@StanczakDominik
Copy link
Member

image
Interestingly, the PR builder now shows the PR number instead of the version. I wonder whether that's intended? Giles shows 0.4, as it should, so I assume this is just a quirk of RTD's test pr builder and should work fine.

StanczakDominik
StanczakDominik approved these changes Jul 26, 2020
View reviewed changes
docs/conf.py Show resolved Hide resolved
docs/conf.py Show resolved Hide resolved
docs/conf.py Show resolved Hide resolved
docs/conf.py Show resolved Hide resolved
docs/_templates/breadcrumbs.html Show resolved Hide resolved
docs/_templates/footer.html Show resolved Hide resolved
docs/index.rst Show resolved Hide resolved
docs/index.rst Show resolved Hide resolved
@rocco8773
Copy link
Member Author

image
Interestingly, the PR builder now shows the PR number instead of the version. I wonder whether that's intended? Giles shows 0.4, as it should, so I assume this is just a quirk of RTD's test pr builder and should work fine.

I do think it's an RTD things. This little bit of code is what defines the behavior.

@StanczakDominik
Copy link
Member

All right, could merge it whenever you like :)

@rocco8773
Copy link
Member Author

Awesome! Thanks for the quick review.

@rocco8773 rocco8773 merged commit 7e6d7a0 into PlasmaPy:master Jul 26, 2020
@rocco8773 rocco8773 mentioned this pull request Jul 27, 2020
Merged
rocco8773 added a commit that referenced this pull request Jul 27, 2020
@rocco8773
Follow up to #875 (#877)
98d3c20
@rocco8773 rocco8773 mentioned this pull request Sep 14, 2020
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@StanczakDominik StanczakDominik StanczakDominik approved these changes

Assignees

@rocco8773 rocco8773

Labels
docs PlasmaPy Docs at http://docs.plasmapy.org
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Thumbnails missing/broken on plasmapy documentation webpage home
2 participants
@rocco8773 @StanczakDominik