TANGO DOCUMENTATION REVIEW

BECKY AUGER-WILLIAMS

18/09/2024

CURRENT DOCUMENTATION

What has been reviewed:

• Tango Controls readthedocs: �https://tango-controls.readthedocs.io/en/latest/
• pyTango readthedocs:�https://pytango.readthedocs.io/en/latest/

REVIEW

Review spreadsheet:

• https://docs.google.com/spreadsheets/d/1IXCboZY4s3HWk3xW_RLYbaZKnQrd1y3eYDSsPONkkO0/edit?pli=1#gid=0

REVIEW

Review:

• Category within the Grand Unified Theory of Documentation (GUTD)
• Tutorials – learning orientated
• How-to – goal orientated
• Reference – information orientated
• Explanation – understanding orientated
• Language: section specific to a given language
• C++
• Python
• Java

​

REVIEW

• Rating: page content, format etc

​

​

​

​

​

​

​

​

• Comments: details of what needs to be updated

​

REVIEW

Googledoc with summary of general issues across the documentation:

• https://docs.google.com/document/d/1wTgocmZn60abepo165pk0YzvnIgrGdVz3_qyglMBtUI/edit#heading=h.dbq7vbc6xyb�(page 1)

RESTRUCTURE

Ideas:

• Split by audience: ‘Users’ & ‘Developers’
• Further split ‘Users’ to ‘General Users’ & ‘Administrators’

​

• Split by language (pros/cons)
• Links to separate docs?
• Easier to maintain
• Easier to find specific information
• OR contain all documentation in one place?
• Easy to find
• Consistent formatting

User’s Guide

|________ General users

|_______ Tutorials

|_______ How to’s

|_______ Explanations

|________ Administrators

|_______ Tutorials

|_______ How to’s

|_______ Explanations

Developer’s Guide

|________ C++

|_______ How to’s

|_______ Explanations

|_______ References

|________ Python

|_______ How to’s

|_______ Explanations

|_______ References

|________ Java

|_______ How to’s

|_______ Explanations

|_______ References

User’s Guide

|________ General users

|_______ Tutorials

|_______ How to’s

|_______ Explanations

|________ Administrators

|_______ Tutorials

|_______ How to’s

|_______ Explanations

Developer’s Guide

|________ C++

|_______ Link to doc –--> - How to’s

- Explanations

- References

|________ Python

|_______ Link to doc –--> - How to’s

- Explanations

- References

|________ Java

|_______ Link to doc –--> - How to’s

- Explanations

- References

​

OR?

RESTRUCTURE

Full suggested restructure in googledoc:

• https://docs.google.com/document/d/1wTgocmZn60abepo165pk0YzvnIgrGdVz3_qyglMBtUI/edit#heading=h.dbq7vbc6xyb�(Page 6 onwards)

​

RESTRUCTURE

Example applying this structure to the Tango docs:

• file:///home/rjaw/Projects/ESRF/rjw-tango-doc/build/html/index.html

​

Source code on GitLab fork:

• https://gitlab.com/rjwosl/tango-doc/-/tree/restructure?ref_type=heads

GRAND UNIFIED THEORY OF DOCUMENTATION (GUTD)

Refer to: https://docs.divio.com/documentation-system/introduction/

GUTD

Example project – Django:

• https://docs.djangoproject.com/en/dev/#how-the-documentation-is-organized

​

Concerns:

• Django is a big project
• I still think it's a bit confusing in places. They definitely start mixing sections.
• Trickier to apply to big/large projects.
• Each concept/part/section should probably apply the GUTD individually??
• But in the same place or links to other parts of the doc

GUTD

E.g.

How-to:

Device servers

…

…

Explanation:

Device servers

…

…

Reference:

Device servers

…

…

​

Device servers:

How-to

Explanation

References

…

How-to

Explanation

References

link

link

OR?

GUTD

Example applying the GUTD to the Tango Installation section:

• file:///home/rjaw/Projects/ESRF/rjw-tango-doc/build/html/installation/index.html

PDF VERSION

Is this a priority?

​

Will need to make some changes to make this useable (see Page 2 in Googledoc) :

• Links need to be spelt out
• Check image formats
• Add build instructions

JUPYTERBOOKS

Summary:

• It can execute code when building the documentation, e.g. can write a Python script to generate a plot and then plot will be generated during the build
• Can use our current rst files with no problem (so may not have to convert all to markdown)

Issues

• Above is not quite what we’re after ??
• A user cannot just see a piece of code in a browser terminal and execute it to see the output (but can be done locally with installed JupyterHub)

​

JUPYTERBOOKS + BINDER

Binder: repository for Jupyter notebooks – allows you to launch interactive notebooks

• https://mybinder.org/?ref=dataschool.io

​

Demo repo on GitHub:

• https://rjwills28.github.io/testJupyBook/intro.html�

JUPYTERBOOKS + BINDER

Only works for ipynb files.

• These do get generated from the markdown files in the build so could replace markdown source with these but that makes it harder to update
• Can convert rst -> md using `rst2myst`

Less easy on GitLab:

• Example:
• https://test-jupyter-book-rjwosl-6f659100656b8fcfc614c0eeabc65ef96f2911.gitlab.io/intro.html
• Have to add our own link, perhaps to the footer. But this does not go to a specific page - just the general Jupyter Lab interface displaying the repo files.

​

DECISIONS TO BE MADE

How do we want to restructure?

• Separate documents for the different languages or sections within document?

How should we apply the GUTD?

Do we spend time fixing the PDF version?

No - probably not used and not worth time maintaining. Can we remove from RTD?

Do we use JupyterBook?

• Do we want to convert all doc source code to markdown (related to above)?

No - will not benefit us.

Do we want to use something like binder?

No - will not benefit us.

WORK TO BE DONE

TANGO DOCUMENTATION REVIEW -

ADDITIONAL CONTENT

16/10/2024

RTD Subprojects

• Separate projects under the same domain
• Example:
• Main project name: wajr-test-rtd1
• Subproject: wajr-test-rtd2
• RTD URLs:
• Main project: https://wajr-test-rtd1.readthedocs.io/en/latest/
• Subproject: https://wajr-test-rtd1.readthedocs.io/projects/wajr-test-rtd2/en/latest/

​

RTD Subprojects

• Easy linking between projects using intersphinx, e.g.:
• conf.py: https://github.com/rjwills28/test_rtd1/blob/main/docs/source/conf.py
• src:�https://github.com/rjwills28/test_rtd1/blob/main/docs/source/index.rst?plain=1

RTD Subprojects

• Searching doesn’t seem to work quite as advertised…
• Can’t search from parent and get results from subproject?
• Have to specify the project to specifically include the subproject, e.g. from parent doc search with: �“project:wajr-test-rtd2 …”�e.g. “project:wajr-test-rtd2 subproject”

Sphinx Vs. MkDocs

Summary: MkDocs is deemed easier to learn due to Markdown support. Sphinx is consider more mature but steeper learning curve. However can allow for rst & md support.

​

Is it worth the overhead of switching?

SUMMARY FROM LAST MEETING:

DECISIONS TO BE MADE

How do we want to restructure?

• Separate documents for the different languages or sections within document?

Split out the different languages into their own repos with their own maintainers. Provide links within the ‘main’ document (include as subprojects?).

How should we apply the GUTD?

Apply per concept?

Do we spend time fixing the PDF version?

No - probably not used and not worth time maintaining. Can we remove from RTD?

Do we use JupyterBook?

• Do we want to convert all doc source code to markdown (related to above)?

No - will not benefit us.

Do we want to use something like binder?

No - will not benefit us.

Sphinx Vs. MkDocs?

Action Plan

Action Plan