Demonstrate automatic Sphinx openapi

[hmpf]

For #628

Enter docs/, run "make html", look at the result in docs/_build/html/index.html

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[github-actions]

Test results

       7 files     574 suites   21m 36s ⏱️
   462 tests    461 ✔️ 1 💤 0 ❌
3 234 runs  3 227 ✔️ 7 💤 0 ❌

Results for commit f9d3f37.

♻️ This comment has been updated with latest results.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.61%. Comparing base (6488afa) to head (f9d3f37).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #648   +/-   ##
=======================================
  Coverage   84.61%   84.61%           
=======================================
  Files          75       75           
  Lines        3750     3750           
=======================================
  Hits         3173     3173           
  Misses        577      577           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[hmpf]

I suspect this is a bug in the sphinx plugin:

reading sources... [100%] site-specific-settings
WARNING: unknown directive or role name: django:setting
<openapi>:1: ERROR: Unexpected indentation.
/home/hm/GIT/campus/argus/Argus/docs/openapi.rst:2416: WARNING: Block quote ends without a blank line; unexpected unindent.
<openapi>:1: ERROR: Unexpected indentation.
/home/hm/GIT/campus/argus/Argus/docs/openapi.rst:2422: WARNING: Block quote ends without a blank line; unexpected unindent.

[johannaengland]

I think you need to also change the .readthedocs.yaml file to make it install the added optional dependencies. I think you can use the extra_requirements option in https://docs.readthedocs.io/en/stable/config-file/v2.html#packages

Otherwise this seems to work. Even though the look of it could be improved.

[lunkwill42]

Looks like a good start, but it really needs to explain how argus-openapi.yml is generated.

Also, some of the output looks weird with our chosen Sphinx templates, like the Status codes from this example:

[podliashanyk]

Thats a functioning POC 👍
There are improvements that could be made in the future:

• those mentioned above
• contrast errors should be fixed. The WAVE accessibility tool shows whooping 500 contrast errors, but it seems that they all concern the yellow and the green text as shown below:

• indentations should be fixed so that alignment of the same level elements matches, and so that indentations are more uniform in general:

• Some indentations could probably be increased for better readability in my opinion (Parameters, Status codes etc elements)
• Some indentations could be reduced for better readability in my opinion:

[hmpf]

Thats a functioning POC 👍 There are improvements that could be made in the future:

• those mentioned above
• contrast errors should be fixed. The WAVE accessibility tool shows whooping 500 contrast errors,
  but it seems that they all concern the yellow and the green text
• indentations should be fixed so that alignment of the same level elements matches, and so that
  indentations are more uniform in general
• Some indentations could probably be increased for better readability in my opinion
  (Parameters, Status codes etc elements)
• Some indentations could be reduced for better readability in my opinion

I don't know how much of this is controlled by our sphinx theme or whether we'd have to fork the plugin to make the changes.

[hmpf]

Replacing the default sphinx theme (alabaster) with "sphinx_rtd_theme" yields this:

What do you think, @podliashanyk?

[johannaengland]

Replacing it with "sphinx_rtd_theme" is also nice, since we use the same for NAV!

[hmpf]

The API looks like barf with sphinx_rtd_theme, the indents don't make sense. I'll add some more screenshots.

[hmpf]

• Sphinx Themes Gallery
• Styling html made by sphinx
• Making a theme

[hmpf]

Theme: "sphinx_rtd_theme"

sphinx_rtd_theme at theme gallery

[hmpf]

Theme: "sphinx_book_theme"

sphinx_book_theme at gallery

This also has a darkmode-theme.

[hmpf]

Theme: "furo"

furo on gallery

It is possible to tune a lot with furo: https://pradyunsg.me/furo/customisation/

[hmpf]

I don't think this will be ready for next release.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud