Taranta Doc Setup¶
This section will explain about setting up the documentation for 4 taranta repos. Doc pages for the 4 taranta repos can be found on SKA Taranta Suite. On this page we will discuss about testing doc changes on local, creating doc, creating build and verifying doc build
Theese steps are similar for all 4 taranta repos. Lets start with the one below:
Testing doc on dev:¶
To compile and test your doc changes on local dev environment, navigate to respective repo and open terminal and run below command:
docker run -it --rm -v $(pwd):/tmp -w /tmp/docs netresearch/sphinx-buildbox bash
make html
Setting up sphinx doc:¶
To create a sphinx doc:
First import gitlab repo in ReadTheDocs. This will create an empty doc website.
Get webhook address and secret: Navigate to Admin > Integration > Gitlab incoming webhook in readthedocs. This will show address and secret to configure webhook in gitlab
Navigate to repo in gitlab > Settings > Webhook > Add new webhook. Use address & secret from step 2 to populate URL & secret token here.
Select the trigger event (eg. Push events, Merge request events, etc.) which will invoke the doc build on readthedocs. Finally click
Add webhook
to add the webhook.After adding webhook, navigate to webhook page, click on
Test
button, this will trigger build on readthedocs
Creating doc for custom branch:¶
There are times when we want to deploy our custom (non develop) branch on readthedocs. To do so follow below steps:
Navigate to
versions
tab on projects readthedocs. For eg. https://readthedocs.org/projects/taranta-auth/versions/ in our caseJump to
Activate a version
and type the name of branch. For eg. ct-1110-fix-doc-issue. Then hit Filter Inactive Versions button.Select your branch and hit
Activate
button next to it. This will direct you to select build variables. ClickActive
checkbox to make it visible.Hit
Save
button. This will create a build for your branch, navigate toBuilds
menu to see its status.After successful build creation, navigate to repos doc page, at the bottom left, click on
v:latest
link.Finally select your branch from the dialog. For eg. ct-1110-fix-doc-issue in our case.
After clicking on custom branch, it will redirect you to your custom branch doc. For eg. https://taranta-auth.readthedocs.io/en/ct-1110-fix-doc-issue/ in our case.
Contribution & Help:¶
In order to contribute or to get assistance from Taranta Team, please reach out to us on Taranta Collab Slack