-
Notifications
You must be signed in to change notification settings - Fork 361
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.
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
Change internal links to ref
role in user documentation
#2214
Conversation
doc/userdoc/documentation_workflow/user_documentation_workflow.rst
Outdated
Show resolved
Hide resolved
Co-authored-by: Pooja Babu <75320801+pnbabu@users.noreply.github.com>
doc/userdoc/community.rst
Outdated
@@ -32,7 +32,7 @@ We have compiled a `list of NEST-related peer-reviewed publications <https://ww | |||
we update regularly. | |||
|
|||
If you have used NEST in your research, let us know! | |||
Don't forget to :doc:`cite NEST <citing-nest>` in your work. | |||
Don't forget to :ref:`cite NEST <cite_nest>` in your work. | |||
|
|||
Have a talk or poster where you used NEST? `Download our logo <https://github.com/nest/nest-simulator/tree/master/extras/logos>`_! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Have a talk or poster where you used NEST? `Download our logo <https://github.com/nest/nest-simulator/tree/master/extras/logos>`_! | |
Have a talk or poster where you used NEST? `Download our logo <https://github.com/nest/nest-simulator/tree/master/doc/logos>`_! |
…imulator into add-ref-role-doc
Co-authored-by: med-ayssar <med.ayssar@gmail.com>
@pnbabu @med-ayssar I found some additional broken links in the models directory that I also updated to the ref role |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me!
Looks fine to me too. |
…imulator into add-ref-role-doc
ref
role in user documentation
This PR changes nearly all the internal links that use
:doc:
to:ref:
The main reason is that the :doc: role requires the relative path, and anytime the source file is moved, all links to the file in the documentation need updating.
With the :ref: role, no path is required, but each page needs to include a label to use as a reference.
We are anticipating changes to the organization of the doc source files, and this makes it easier to not have to worry about all mentions of a file.
Every reStructuredText file in userdoc/ got a label. Most* :doc: roles are changed to :ref:.
In addition, many broken links were fixed.
The styleguide is also updated to include the preference for using the :ref: role.
*There are still some :doc: roles in the files, because with everything there are exceptions:
Links to external projects using intersphinx, Python files, Jupyter notebooks, and autogenerated files (models and examples) still use the :doc: role.
During build, Sphinx spits out warnings of "undefined label" when a it can't find the internal reference. These have been checked and should all be resolved.