Release an online version¶
Every time you make a modification to the documentation, you are required to:
- branch out from develop to a
feature/FEATURE_NAME
branch (seeCode Collaboration
) - make the necessary modifications (see
Sphinx Documentation
) - test the build locally (see
Sphinx Documentation)
- update the
CHANGELOG.md
- open a Pull Request into
develop
(seeCode Collaboration
) - issue an unstable version of the documentation (see
Release Versioning
)
The reviewer is required to:
- review the pull request by testing it locally
- if needed, ask the developer for modifications
- merge into develop, push and check the result online (
latest
version) - release a stable version with
bumpversion
- merge develop into master to deploy a
stable
version of the docs
To host our online documentation, like the one you are reading, we use readthedocs.
Deploying a version with readthedocs
¶
Readthedocs uses git tags to build different versions of the documentation, with two additional versions:
latest
(corresponding to the latest commit ondevelop
)stable
(corresponding to the most recent version released onmaster
)
Once commits are pushed to the develop
branch on origin
(or a new
version tag is pushed to main
), the documentation is built
automatically by readthedocs. If changes are pushed
to other branches, no documentation is built.
Stable vs. unstable versions¶
Depending whether the release is stable or unstable, different things happen:
- if the release is stable (e.g., v0.1.2), the resulting documentation is published on the website and a new version will be visible in the readthedocs menu)
- if the release is unstable (e.g., v0.1.2dev0), the resulting documentation will not be built nor published on the website
Activating unstable versions¶
Unpublished versions, such as unstable versions or versions from other branches, can still be activated by authorized users (i.e., readthedocs maintainers) to be viewed online and shared with others through a link. This can be done by clicking on the readthedocs menu and selecting "Builds", then "Versions" and activate build. Make it hidden to avoid it being listed on the website and searchable by the users.
Clicking on the right build allows to see it in the browser and copy the related link to share it with collaborators. This is particularly useful to share drafts of the output documentation without modifying stable versions.
How different versions are used in tudat¶
This is how we envisage different versions of the online docs:
- the
stable
documentation with proper versioning is the official documentation and can be linked to different software versions - the
latest
documentation is useful to deploy documentation quickly and, if needed, also use it for giving/receiving feedback - the inactive documentation (corresponding to unstable versions or other branches) can be used for giving/receiving feedback, but they have to be activated and hidden by maintainers of readthedocs
Troubleshooting¶
In this section, we collect the most recurring bugs that can happen
while using readthedocs
, hoping that it will save precious time to
future Tudat contributors.
No changes shown in online docs¶
It can happen that, after pushing your changes to the origin
repository, no changes are shown on the actual website (e.g., on
tudat-space or on this website). Some suggestions to identify the
problem will follow:
- Check that you pushed to the
main
branch. The documentation is built by readthedocs only if changes are pushed to that branch. - Check that the build was successful. This can be monitored via the "Builds" link in the readthedocs_menu (see screenshot above). If the build was not successful, you can click on it and see the output of the build. This can be helpful to identify where things are going wrong.