Switch docs theme #4276

lilyminium · 2023-09-04T10:56:25Z

Fixes MDAnalysis/mdanalysis-sphinx-theme#33
Fixes #4199

Changes made in this Pull Request:

PR Checklist

Tests?
Docs?
CHANGELOG updated?
Issue raised/referenced?

Developers certificate of origin

I certify that this contribution is covered by the LGPLv2.1+ license as defined in our LICENSE and adheres to the Developer Certificate of Origin.

📚 Documentation preview 📚: https://mdanalysis--4276.org.readthedocs.build/en/4276/

github-actions · 2023-09-04T10:58:57Z

Linter Bot Results:

Hi @lilyminium! Thanks for making this PR. We linted your code and found the following:

Some issues were found with the formatting of your code.

Code Location	Outcome
main package	⚠️ Possible failure
testsuite	✅ Passed

Please have a look at the darker-main-code and darker-test-code steps here for more details: https://github.com/MDAnalysis/mdanalysis/actions/runs/6077561192/job/16496321590

Please note: The black linter is purely informational, you can safely ignore these outcomes if there are no flake8 failures!

IAlibay

Thanks @lilyminium, awesome work!

.github/workflows/gh-ci.yaml

codecov · 2023-09-04T11:13:30Z

Codecov Report

Patch and project coverage have no change.

Comparison is base (b2b3eb9) 93.40% compared to head (a48a41c) 93.40%.
Report is 13 commits behind head on develop.

Additional details and impacted files

@@            Coverage Diff             @@
##           develop    #4276     +/-   ##
==========================================
  Coverage    93.40%   93.40%             
==========================================
  Files          170      184     +14     
  Lines        22250    23358   +1108     
  Branches      4071     4071             
==========================================
+ Hits         20783    21818   +1035     
- Misses         951     1024     +73     
  Partials       516      516

Files Changed	Coverage Δ
package/MDAnalysis/analysis/bat.py	`94.57% <ø> (ø)`
package/MDAnalysis/analysis/contacts.py	`100.00% <ø> (ø)`
package/MDAnalysis/analysis/data/filenames.py	`100.00% <ø> (ø)`
package/MDAnalysis/analysis/diffusionmap.py	`100.00% <ø> (ø)`
package/MDAnalysis/analysis/dihedrals.py	`97.05% <ø> (ø)`
package/MDAnalysis/analysis/encore/similarity.py	`85.62% <ø> (ø)`
package/MDAnalysis/analysis/gnm.py	`97.61% <ø> (ø)`
package/MDAnalysis/analysis/helix_analysis.py	`98.65% <ø> (ø)`
package/MDAnalysis/analysis/hole2/__init__.py	`100.00% <ø> (ø)`
...DAnalysis/analysis/hydrogenbonds/hbond_analysis.py	`97.22% <ø> (ø)`
... and 28 more

... and 14 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

lilyminium · 2023-09-04T11:31:24Z

On ReadTheDocs, we have some remnant blue boxes:

On my machine (TM), we do not:

Moving to draft status while I figure it out...

Edit: Ok, I can reproduce this if I use the same bewilderingly old version of sphinx_rtd_theme (0.4.3) that RTD is using.

IAlibay · 2023-09-04T11:45:46Z

Ok, I can reproduce this if I use the same bewilderingly old version of sphinx_rtd_theme (0.4.3) that RTD is using.

Is this one of those where we can just say we don't care and it'll go away soon or is that being too hopeful?

lilyminium · 2023-09-04T11:48:43Z

Is this one of those where we can just say we don't care and it'll go away soon or is that being too hopeful?

I could maybe pin sphinx_rtd_theme >=1 with mdanalysis_sphinx_theme to resolve this? (or would RTD just ignore that version and go for the more permissive variant?) It is a very weirdly old version (released 2019, sphinx_rtd_theme is on 2.0.0rc2 atm) and I'm curious why RTD has picked it. It'd be a bit annoying if we couldn't preview our docs properly there.

User guide is picking up the same 0.4.3...

IAlibay · 2023-09-04T11:50:08Z

Is this one of those where we can just say we don't care and it'll go away soon or is that being too hopeful?

I could maybe pin sphinx_rtd_theme >=1 with mdanalysis_sphinx_theme to resolve this? (or would RTD just ignore that version and go for the more permissive variant?) It is a very weirdly old version (released 2019, sphinx_rtd_theme is on 2.0.0rc2 atm) and I'm curious why RTD has picked it. It'd be a bit annoying if we couldn't preview our docs properly there.

I guess you could try just override the version in the yaml file here for now and see what happens? If that doesn't work then they are doing some annoying black magic in the background that is unlikely get fixed with pinning upstream.

IAlibay · 2023-09-04T12:00:22Z

 + sphinx_rtd_theme                      1.3.0  pyha770c72_0        conda-forge/noarch         2 MB

Seems to have done a thing?

TIL RTD actually advocates for pinning the sphinx_rtd_theme version: https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html#id2

lilyminium · 2023-09-04T12:04:03Z

Oh nice! I was just tracking stuff down myself, since everywhere seemed to be picking up the 0.4.3 version. I think it might be preferring anaconda/noarch (https://anaconda.org/anaconda/sphinx_rtd_theme), which tops out at 0.4.3, over conda-forge (https://anaconda.org/conda-forge/sphinx_rtd_theme).
So we could either pin the lower bound of sphinx_rtd_theme, or keep pinning every version as they release (a minor pain...), and I assume as long as it's above a certain version it should pick up the conda-forge one? Do you have any preference -- I know you generally prefer as few pins as possible?

Edit: whoops, I should have let RTD finish building before pushing the rebase :/ sorry for the wait

IAlibay · 2023-09-04T12:06:12Z

So we could either pin the lower bound of sphinx_rtd_theme, or keep pinning every version as they release (a minor pain...), and I assume as long as it's above a certain version it should pick up the conda-forge one? Do you have any preference -- I know you generally prefer as few pins as possible?

Less work is better work. I would just go with the lower bound pin? Would it make sense to just have the pin upstream in the new theme? It's annoying to add a dependency, but it would probably save you some headaches later?

lilyminium · 2023-09-04T12:10:12Z

Yeah I'll pin upstream.

orbeckst

This looks super-nice already on RTD. Great work! I look forward to seeing it merged.

lilyminium · 2023-09-05T01:03:37Z

Thanks! I think this is ready for review now. The theme fixes a few small annoying issues, plus the docutils incompatibility. There are also minor docs fixes I noticed from previewing docs.

Old

New

IAlibay

Could you tick the lgplv2 box?

Otherwise, lgtm! This is really awesome, thanks @lilyminium ! 🎉

IAlibay · 2023-09-05T02:24:26Z

package/MDAnalysis/analysis/bat.py

@@ -31,11 +31,11 @@

 This module contains classes for interconverting between Cartesian and an
 internal coordinate system, Bond-Angle-Torsion (BAT) coordinates
-:cite:p:`Chang2003`, for a given set of atoms or residues. This coordinate
+:footcite:p:`Chang2003`, for a given set of atoms or residues. This coordinate


Do we document how we do citations anywhere in our docs? We probably should tell folks that cite -> footcite now

Are there any peculiarities to footbibliography that should be stated somewhere? (I don't know how/if it differs from the old approach)

Ticked :)

I don't think so, no more than bibliography is. The footbib is used for local bibliographies (on the same page as the reference), so we can remove stuff like the a- and b- prefixes we had before. The normal bibliography is for global bibliographies, so one reference list for the entire repo. This is all readily available on the sphinx bibtex extension docs though. I was planning to add in some notes in the mdanalysis-sphinx-theme -- MDAnalysis/mdanalysis-sphinx-theme#26

The one catch is that there's meant to be one footbib per reference per page, so if footbibliographies are created multiple times for the same reference, then only the first one will ahve the reference and all links will go there. Again I got this from the official docs.

Could you maybe raise an issue in the userguide for docs on this? This is the kind of info any contributor new or old should be told to look at so imho, even if it's just a reference to the theme docs, your above explanation should exist there in some way.

github-actions bot added Component-Analysis Component-Converters Component-Core Component-lib Component-Readers Component-Topology Continuous Integration labels Sep 4, 2023

IAlibay reviewed Sep 4, 2023

View reviewed changes

.github/workflows/gh-ci.yaml Outdated Show resolved Hide resolved

lilyminium mentioned this pull request Sep 4, 2023

Move on from build_sphinx #4277

Closed

lilyminium marked this pull request as draft September 4, 2023 11:31

lilyminium added 12 commits September 4, 2023 22:04

switch theme

b52e24d

reformat bibliography to footbibliograpy for rendering

948cee2

change bib styling to footbib

105dfa5

remove indentation blockquote from bat analysis

46fb6c8

fixed maths and variable formatting

2e1609a

fix output formatting

3b128c7

fix formatting

08b9a3d

fix docs bib...

43458b6

fix list formatting

f1425ea

add docs for functions and classes

0ad0414

mass change all bibliograhpies to local

4bed9f6

fix formatting in warning

3228103

lilyminium added 17 commits September 4, 2023 22:04

add dlpoly classes to docs

2de8d29

fix itp docs formatting

8794df9

fix class reference

c08aa72

fix docs

8c728a4

fix indent

430e23d

fix more indent

39a8006

more indent

02104ef

fix all the indents

938e134

fix code formatting

cdb9ebb

fix seealso formatting

629482a

unindent

dfdc31e

fix indent and deprecation warnings

37ceafe

fix formatting

00057de

add deps

0bdf2ad

rm logos for now

49ca33a

rm dep pins

7664d4c

lower pin rtd theme

7ccfaf4

lilyminium force-pushed the switch-docs-theme branch from bf6f558 to 7ccfaf4 Compare September 4, 2023 12:05

lilyminium mentioned this pull request Sep 4, 2023

Add sphinx pin and files to manifest MDAnalysis/mdanalysis-sphinx-theme#48

Merged

4 tasks

wait for 1.0.1...

a48a41c

IAlibay closed this Sep 4, 2023

IAlibay reopened this Sep 4, 2023

orbeckst reviewed Sep 4, 2023

View reviewed changes

lilyminium marked this pull request as ready for review September 5, 2023 01:03

IAlibay approved these changes Sep 5, 2023

View reviewed changes

IAlibay merged commit c289b7f into MDAnalysis:develop Sep 5, 2023
29 of 33 checks passed

IAlibay added the maintainability label Sep 21, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Switch docs theme #4276

Switch docs theme #4276

lilyminium commented Sep 4, 2023 •

edited

Loading

github-actions bot commented Sep 4, 2023 •

edited

Loading

IAlibay left a comment

codecov bot commented Sep 4, 2023 •

edited

Loading

lilyminium commented Sep 4, 2023 •

edited

Loading

IAlibay commented Sep 4, 2023

lilyminium commented Sep 4, 2023 •

edited

Loading

IAlibay commented Sep 4, 2023

IAlibay commented Sep 4, 2023

lilyminium commented Sep 4, 2023 •

edited

Loading

IAlibay commented Sep 4, 2023

lilyminium commented Sep 4, 2023

orbeckst left a comment

lilyminium commented Sep 5, 2023

IAlibay left a comment

IAlibay Sep 5, 2023

IAlibay Sep 5, 2023

lilyminium Sep 5, 2023

IAlibay Sep 5, 2023

lilyminium Sep 5, 2023

Switch docs theme #4276

Switch docs theme #4276

Conversation

lilyminium commented Sep 4, 2023 • edited Loading

Changes made in this Pull Request:

PR Checklist

Developers certificate of origin

github-actions bot commented Sep 4, 2023 • edited Loading

Linter Bot Results:

IAlibay left a comment

Choose a reason for hiding this comment

codecov bot commented Sep 4, 2023 • edited Loading

Codecov Report

lilyminium commented Sep 4, 2023 • edited Loading

IAlibay commented Sep 4, 2023

lilyminium commented Sep 4, 2023 • edited Loading

IAlibay commented Sep 4, 2023

IAlibay commented Sep 4, 2023

lilyminium commented Sep 4, 2023 • edited Loading

IAlibay commented Sep 4, 2023

lilyminium commented Sep 4, 2023

orbeckst left a comment

Choose a reason for hiding this comment

lilyminium commented Sep 5, 2023

IAlibay left a comment

Choose a reason for hiding this comment

IAlibay Sep 5, 2023

Choose a reason for hiding this comment

IAlibay Sep 5, 2023

Choose a reason for hiding this comment

lilyminium Sep 5, 2023

Choose a reason for hiding this comment

IAlibay Sep 5, 2023

Choose a reason for hiding this comment

lilyminium Sep 5, 2023

Choose a reason for hiding this comment

lilyminium commented Sep 4, 2023 •

edited

Loading

github-actions bot commented Sep 4, 2023 •

edited

Loading

codecov bot commented Sep 4, 2023 •

edited

Loading

lilyminium commented Sep 4, 2023 •

edited

Loading

lilyminium commented Sep 4, 2023 •

edited

Loading

lilyminium commented Sep 4, 2023 •

edited

Loading