Draft: Sphinx Documentation beautify and restructure

paylanonrequested to merge
paylanon/openmw:improved-docs into master

Summary:

This branch gives the OpenMW Documentation a fresh coat of paint, keeping the Sphinx backbone mostly untouched. Resolves #7460 by separating out the lua documentation for openmw.core and openmw.types into subcategories. Resolves #6012 in some part by reorganizing toctrees in a way more convenient for the user.

Issues Resolved:

  • Directory created to flesh out bloated Lua module pages

openmw.core and open.types module pages were replaced with directories, each with their own toctree. The task can be completed like so: expand out the .lua documentation files for each module into separate .lua files, and create an .rst in the directories for each type.

  • openmw.types fleshed out using splitluadoc commit

  • Unused CSS intended for the page fixed and ready to apply

There was a luadocs.css in the _static folder that wasn't being used, due to the ReadTheDocs default theme overriding it. Included in the _static folder now is a working version of this theme, luadocsOriginal.css, with conf.py modified accordingly.

Changes/Improvements:

  • Added OpenMW logo to header, direct from source files
  • Created a new CSS theme, luadocsImproved.css, applied as default
  • Minor rearrangement of navigation headers
  • 'Sticky' scrolling of the contents bar deactivated for ease-of-use

Toctrees were restructured one level up, which I believe makes more sense.

  • Added a header background matching the main website
  • Added syntax highlighting to all relevant code blocks

There was an inconsistency in the doc files where some code blocks were declared without a syntax, and some were. This was fixed where syntax highlighting would be relevant.

  • Recolored code blocks from highlighter-yellow(?) to dark console, with a soft beige option commented
  • Updated Sphinx, Docutils, Jinja2 and sphinx-rtd-theme Python packages to latest compatible versions
  • Added Dark Mode functionality for cosy reading :)

WIP:

  • Applying splitluadoc commit to flesh out Lua module pages
  • Perfecting table formatting
  • Testing speed against original

newOpenMWDocs3

Lots of love

ReadTheDocs Build: openmw-improved-docs.readthedocs.io

Edited by paylanon

Merge request reports