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

Implement version role for Sphinx #2165

Merged
merged 50 commits into from
Nov 3, 2021
Merged

Implement version role for Sphinx #2165

merged 50 commits into from
Nov 3, 2021

Conversation

mahdienan
Copy link
Contributor

@mahdienan mahdienan commented Sep 16, 2021 •
edited by terhorstd

This pr implements a Sphinx extension that allows referencing version numbers of packages in the documentation from a single source (see versions.json) to make sure developers are referencing correct version numbers. The extension defines the version role in VersionSyncRole.py. For example, to display the recommended version of cmake, the role should be used like this :version:`cmake,recommended` .

This extension was written to fix issue #1558.

@mahdienan
added hoverxref configuration
9f2295a
@mahdienan
removed hoverxref usage.
7a28981
@mahdienan
Merge branch 'master' of https://github.com/mahdienan/nest-simulator
b6b35c6
@mahdienan
updated with latest upstream.
0cc08c6
@mahdienan
fixed path to glossary file.
101fe3c
@mahdienan
added example in tutorial part 1.
9bafb44
@mahdienan
fixed glossary path and added further examples in tutorials part 2,3,4.
1a139d8
@mahdienan
fixed glossary term redirection and added more glossary terms.
907321f
@mahdienan
fixed url path for readthedocs build.
fbe77a1
@mahdienan
removed demo from index.rst
47ef543
@mahdienan
changed glossary html url to point at the relative path
cd170c6
@mahdienan
set glossary relative path.
9f174e0
@mahdienan
Merge remote-tracking branch 'upstream/master'
13e919b
@mahdienan
Merge branch 'master' into hoverxtooltip_plugin
a3d922f
@mahdienan
set glossary to absolute path.
c260958
@mahdienan
set glossary relative to base url.
8f89845
@mahdienan
set glossary relative to base url.
a3d06e3
@mahdienan
set glossary relative to base url. (fix)
1ad8cf5
@mahdienan
set glossary relative to base url. (fix)
62b845e
@mahdienan
set glossary relative to base url. (fix)
7d1d736
@mahdienan
set glossary relative to base url. (fix)
207f06f
@mahdienan
set glossary relative to base url. (fix 2)
b8349fe
@mahdienan
set glossary relative to base url. (fix attempt!)
d9b2599
@mahdienan
set glossary relative to base url. (fix attempt!)
724bf45
@mahdienan
set glossary relative to base url. (fix attempt!)
348575c
@mahdienan
set glossary relative to base url. (fix attempt!)
5250db0
@mahdienan
set glossary relative to base url. (fix attempt!)
bb828a4
@mahdienan
set glossary relative to base url. (fix attempt!)
2d8fcfd
@mahdienan
set glossary relative to base url. (fix attempt!)
a4f025b
@mahdienan
set glossary relative to base url. (fix attempt!)
404f0d2
@jessica-mitchell jessica-mitchell added I: No breaking change Previously written code will work as before, no one should note anything changing (aside the fix) S: Normal Handle this with default priority T: Enhancement New functionality, model or documentation labels Sep 17, 2021
@jessica-mitchell jessica-mitchell added this to In progress in Documentation via automation Sep 17, 2021
jessica-mitchell
jessica-mitchell requested changes Oct 13, 2021
View reviewed changes
Copy link
Contributor

@jessica-mitchell jessica-mitchell left a comment

Choose a reason for hiding this comment

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

Thanks @mahdienan, this works as described. :) I just have a couple of minor comments in line.

doc/userdoc/_ext/VersionSyncRole.py Outdated Show resolved Hide resolved
doc/userdoc/_ext/VersionSyncRole.py Show resolved Hide resolved
Documentation automation moved this from In progress to Review Oct 13, 2021
jessica-mitchell
jessica-mitchell approved these changes Oct 21, 2021
View reviewed changes
Copy link
Contributor

@jessica-mitchell jessica-mitchell left a comment

Choose a reason for hiding this comment

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

thanks @mahdienan! I approve

@terhorstd terhorstd self-requested a review October 28, 2021 13:26
@terhorstd terhorstd changed the title Implement Version Role for Read the Docs Implement Version Role for Sphinx Oct 28, 2021
@terhorstd terhorstd linked an issue Oct 28, 2021 that may be closed by this pull request
Replace fixed version numbers in documentation by custom RST directive #1558
Closed
terhorstd
terhorstd approved these changes Oct 28, 2021
View reviewed changes
Copy link
Contributor

@terhorstd terhorstd left a comment

Choose a reason for hiding this comment

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

LGTM 👍

heplesser
heplesser reviewed Oct 28, 2021
View reviewed changes
Copy link
Contributor

@heplesser heplesser left a comment

Choose a reason for hiding this comment

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

I was about to merge, got curious about the content and found a typo and one issue, see below.

doc/userdoc/_ext/VersionSyncRole.py Outdated Show resolved Hide resolved
doc/userdoc/_ext/versions.json Outdated Show resolved Hide resolved
mahdienan and others added 2 commits October 28, 2021 17:28
@mahdienan @heplesser
Update doc/userdoc/_ext/VersionSyncRole.py
175393c 
Co-authored-by: Hans Ekkehard Plesser <hans.ekkehard.plesser@nmbu.no>
@terhorstd
Update versions.json
2f8a4a2
@jougs jougs merged commit dc786de into nest:master Nov 3, 2021
Documentation automation moved this from Review to Done Nov 3, 2021
@jougs jougs changed the title Implement Version Role for Sphinx Implement version role for Sphinx Nov 3, 2021
@terhorstd terhorstd mentioned this pull request Nov 5, 2021
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@heplesser heplesser heplesser left review comments

@jougs jougs jougs left review comments

@jessica-mitchell jessica-mitchell jessica-mitchell approved these changes

@terhorstd terhorstd terhorstd approved these changes

Assignees
No one assigned
Labels
I: No breaking change Previously written code will work as before, no one should note anything changing (aside the fix) S: Normal Handle this with default priority T: Enhancement New functionality, model or documentation
Projects
Documentation
  
Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Replace fixed version numbers in documentation by custom RST directive
5 participants
@mahdienan @heplesser @jougs @jessica-mitchell @terhorstd