Demonstrate automatic Sphinx openapi

[hmpf]

For #628

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

[sonarqubecloud[bot]]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[github-actions[bot]]

Test results

       7 files     574 suites   21m 36s :stopwatch:    462 tests    461 :heavy_check_mark: 1 :zzz: 0 :x: 3 234 runs  3 227 :heavy_check_mark: 7 :zzz: 0 :x:

Results for commit f9d3f373.

:recycle: This comment has been updated with latest results.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

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           

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: 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.

[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[bot]]

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