#1731 Read the Docs configuration file v2

[ggnaegi]

Fixes #1731

• 1731

Proposed Changes

• add .readthedocs.yaml file to the root folder.
• update to the latest sphinx version, update conf.py

Blog article: Migrate your project to .readthedocs.yaml configuration file v2 — Read the Docs Blog

I just tried myself https://ocelot-test.readthedocs.io/en/latest/features/authentication.html

[ggnaegi]

@raman-m Ok, done, you can merge

[raman-m]

@raman-m Ok, done, you can merge

Not yet! 😉

[raman-m]

First,

The copyright message looks strange: https://ocelot-test.readthedocs.io/en/latest/index.html Copyright is located at the bottom of each page! It is 2023 year now and project belongs to ThreeMammals org. The line: docs/conf.py | Line 62

Second,

Version of docs is 1.0.0 !!! 🤣 So, HTML doc title contains this info: But actually version should be 20.0 because of current release 20.0 So, it is hardcoded now in config:

# The short X.Y version.
version = '1.0.0'

The line: docs/conf.py | Line 70

Third,

Release info is also wrong, it is 1.0.0 now. But I didn't find how it is reflected to documentation files.

# The full version, including alpha/beta/rc tags.
release = '1.0.0'

The line: docs/conf.py | Line 72

I propose to fix these issues. Hardcode for this hotfix is OK. But in future we have to write dynamic calculation of copyright year, version and release variables.

[raman-m]

Important blog article

Doctools without configuration file (conf.py / mkdocs.yml) are deprecated — Read the Docs Blog on 12 July 2023

[ggnaegi]

@raman-m So, you can check it here: https://ocelot-test.readthedocs.io/en/bug-fix_documentation_generation

I have added the requirements.txt file, made some improvements in the doc (fixing documentation compilation warnings), fixed the copyrights and versions.

[raman-m]

(fixing documentation compilation warnings)

What are you talking about?

[raman-m]

@raman-m So, you can check it here: https://ocelot-test.readthedocs.io/en/bug-fix_documentation_generation

I have added the requirements.txt file, made some improvements in the doc (fixing documentation compilation warnings), fixed the copyrights and versions.

Thank you!

[ggnaegi]

(fixing documentation compilation warnings)

What are you talking about?

When building the documentation locally...

That's what I fixed.

D:\dev\repositories\sphinx_test\building/releaseprocess.rst:19: WARNING: Enumerated list ends without a blank line; unexpected unindent.
D:\dev\repositories\sphinx_test\features/authentication.rst:173: WARNING: Title underline too short.

Allowed Scopes
^^^^^^^^^^^^^
D:\dev\repositories\sphinx_test\features/authentication.rst:173: WARNING: Title underline too short.

Allowed Scopes
^^^^^^^^^^^^^
D:\dev\repositories\sphinx_test\features/claimstransformation.rst:18: WARNING: Title underline too short.

Claims to Claims Transformation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
D:\dev\repositories\sphinx_test\features/claimstransformation.rst:45: WARNING: Title underline too short.

Claims to Query String Parameters Transformation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
D:\dev\repositories\sphinx_test\features/claimstransformation.rst:45: WARNING: Title underline too short.

Claims to Query String Parameters Transformation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
D:\dev\repositories\sphinx_test\features/kubernetes.rst:31: WARNING: Explicit markup ends without a blank line; unexpected unindent.
D:\dev\repositories\sphinx_test\features/kubernetes.rst:57: WARNING: Explicit markup ends without a blank line; unexpected unindent.
D:\dev\repositories\sphinx_test\features/loadbalancer.rst:105: WARNING: Title underline too short.

Custom Load Balancers
^^^^^^^^^^^^^^^^^^^^
D:\dev\repositories\sphinx_test\features/loadbalancer.rst:105: WARNING: Title underline too short.

Custom Load Balancers
^^^^^^^^^^^^^^^^^^^^
D:\dev\repositories\sphinx_test\features/tracing.rst:2: WARNING: Duplicate explicit target name: "here".
D:\dev\repositories\sphinx_test\features/websockets.rst:76: WARNING: Explicit markup ends without a blank line; unexpected unindent.

[raman-m]

@ggnaegi commented on Oct 15

My local build results: I have 3 warnings! 😄

[ggnaegi]

@raman-m commented

@raman-m Yeah, rebuild it again and it's going to be fine, only the static folder 😁

My concern is now the following: what about main branch?

[raman-m]

@ggnaegi commented My concern is now the following: what about main branch?

I will create a PR to main from this release branch incoming days. The PR must be approved by Raynald. And then, we will get new release. And will check actual Docs build here: https://ocelot.readthedocs.io/ I will keep you updated...