Merge branch 'docs_openmw_cfg' into 'master'

Improve docs styling for code blocks and headers

See merge request OpenMW/openmw!4733

docs/source/_ext/omw-lexers.py

@@ -0,0 +1,19 @@
+from pygments.lexer import RegexLexer, bygroups
+from pygments.token import Comment, Name, Operator, String, Text
+from sphinx.highlighting import lexers
+
+class OMWConfigLexer(RegexLexer):
+    name = 'openmwcfg'
+    aliases = ['openmwcfg']
+    filenames = ['openmw.cfg']
+
+    tokens = {
+        'root': [
+            (r'(\s*)(#.*$)', bygroups(Text.Whitespace, Comment.Single)),
+            (r'(\s*)([a-zA-Z0-9_.+-]+)(\s*(\+)?=\s*)(.*)',  bygroups(Text.Whitespace, Name.Attribute, Operator, Operator, String)),
+            (r'.+\n', Text),
+        ],
+    }
+
+def setup(_):
+    lexers["openmwcfg"] = OMWConfigLexer()

docs/source/_static/theme-override.css

@@ -138,3 +138,17 @@ tbody tr:hover {
 #left-sidebar {
     overflow-y: scroll;
 }
+
+#content div[class^=highlight], #content pre.literal-block, p, h4, h5, h6 {
+    margin-bottom: 1.5rem;
+}
+
+h5 {
+    font-size: 1.15rem;
+    font-weight: 600;
+}
+
+h6 {
+    font-size: 1.08rem;
+    font-weight: 600;
+}

docs/source/conf.py

@@ -43,7 +43,8 @@ extensions = [
     'sphinx.ext.viewcode',
     'sphinx.ext.autosectionlabel',
     'sphinx_design',
-    'omw-directives'
+    'omw-directives',
+    'omw-lexers',
 ]
 
 #autosectionlabel_prefix_document = True
@@ -138,7 +139,7 @@ exclude_patterns = []
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'default'
 pygments_style_dark = 'github-dark'
 
 # A list of ignored prefixes for module index sorting.

docs/source/manuals/installation/install-game-files.rst

@@ -81,15 +81,15 @@ For Distributions Using `apt` (e.g., Ubuntu, Debian)
 
 .. code:: console
 
-    sudo apt update
+    $ sudo apt update
-    sudo apt install innoextract
+    $ sudo apt install innoextract
 
 For macOS using Homebrew
 ++++++++++++++++++++++++
 
 .. code:: console
 
-    brew install innoextract
+    $ brew install innoextract
 
 Once innoextract is installed, download the game from GOG. The downloaded file should be called ``setup_tes_morrowind_goty_2.0.0.7.exe`` or something similar. When ``innoextract`` is run on it, it will extract the files directly into the folder the ``setup.exe`` file is located. If you have a specific folder where you want it to be extracted to, for example in ``~/Documents/Games/Morrowind`` You can specify it with the ``-d`` flag.
 

docs/source/reference/lua-scripting/overview.rst

@@ -126,10 +126,12 @@ The options are:
 
 Enable it in ``openmw.cfg`` the same way as any other mod:
 
-::
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     data=path/to/my_lua_mod
-    content=my_lua_mod.omwscripts  # or content=my_lua_mod.omwaddon
+    # or content=my_lua_mod.omwaddon
+    content=my_lua_mod.omwscripts
 
 Now every time the player presses "X" on a keyboard, a message is shown.
 

docs/source/reference/modding/custom-models/pipeline-blender-collada-animated-creature.rst

@@ -177,7 +177,6 @@ definitions and events. At a minimum it needs to include at least animation
     runforward: stop 4.433333
     attack1: start 4.466667
     attack1: stop 5.433333
-    ...
 
 The textkeys file is placed in the same folder as the model and matches the model's name.
 

docs/source/reference/modding/custom-models/pipeline-blender-collada-static-models.rst

@@ -168,7 +168,7 @@ the file path to the texture is incorrect and OpenMW can't find it.
 To fix this you can open the exported ``.dae`` file in a text editor and check
 the texture's filepath. In the example of this barrel model it's found on lines 13-17.
 
-.. code::
+.. code-block:: xml
     
     <library_images>
         <image id="id-image-4" name="the_barrel">

docs/source/reference/modding/custom-shader-effects.rst

@@ -23,7 +23,8 @@ dungeons.
 To use this feature the :ref:`soft particles` setting must be enabled.
 This setting can either be activated in the OpenMW launcher or changed in `settings.cfg`:
 
-::
+.. code-block:: ini
+    :caption: settings.cfg
 
     [Shaders]
     soft particles = true
@@ -64,7 +65,8 @@ Blue and alpha channels are ignored.
 To use this feature the :ref:`post processing <Post Processing>` setting must be enabled.
 This setting can either be activated in the OpenMW launcher, in-game, or changed in `settings.cfg`:
 
-::
+.. code-block:: ini
+    :caption: settings.cfg
 
     [Post Processing]
     enabled = true

docs/source/reference/modding/extended.rst

@@ -91,7 +91,8 @@ The behavior of such a model:
 
 The actual state toggling time depends on the sunrise/sunset time settings in `openmw.cfg`:
 
-::
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     fallback=Weather_Sunrise_Time,6
     fallback=Weather_Sunset_Time,18
@@ -102,7 +103,8 @@ These settings lead to the "night" starting at 20:00 and ending at 6:00.
 
 The engine checks if the weather is bright enough to support the "interior day" mode using the Glare_View setting. If it is >= 0.5, the engine considers the weather bright.
 
-::
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     fallback=Weather_Clear_Glare_View,1
     fallback=Weather_Foggy_Glare_View,0.25
@@ -138,7 +140,8 @@ If you want to override walking animations, you should override ``xbase_anim_fem
 
 To enable this feature, you should have this line in your settings.cfg:
 
-::
+.. code-block:: ini
+    :caption: settings.cfg
 
     [Game]
     use additional anim sources = true
@@ -157,7 +160,8 @@ This feature conflicts with old mods which use scripted scabbards, arrows with p
 
 The minimum you need is the ``xbase_anim_sh.nif`` file from the `Weapon Sheathing`_ mod and this line in your settings.cfg:
 
-::
+.. code-block:: ini
+    :caption: settings.cfg
 
     [Game]
     weapon sheathing = true
@@ -205,7 +209,8 @@ Skeleton extensions
 
 It is possible to inject custom bones into actor skeletons:
 
-::
+.. code-block:: ini
+    :caption: settings.cfg
 
     [Game]
     use additional anim sources = true
@@ -323,14 +328,16 @@ General advices to create assets for this feature:
 
 Groundcover mods can be registered in the openmw.cfg via "groundcover" entries instead of "content" ones:
 
-::
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     groundcover=my_grass_mod.esp
 
 Every static from such mod is treated as a groundcover object.
 Also groundcover detection should be enabled via settings.cfg:
 
-::
+.. code-block:: ini
+    :caption: settings.cfg
 
     [Groundcover]
     enabled = true

docs/source/reference/modding/font.rst

@@ -3,6 +3,9 @@ Fonts
 
 Default UI font and font used in magic scrolls are defined in ``openmw.cfg``:
 
+.. code-block:: openmwcfg
+  :caption: openmw.cfg
+
   fallback=Fonts_Font_0,MysticCards
   fallback=Fonts_Font_2,DemonicLetters
 
@@ -20,6 +23,9 @@ You can use --export-fonts command line option to write the converted font
 
 They can be used instead of TrueType fonts if needed by specifying their ``.fnt`` files names in the ``openmw.cfg``. For example:
 
+.. code-block:: openmwcfg
+  :caption: openmw.cfg
+
   fallback=Fonts_Font_0,magic_cards_regular
   fallback=Fonts_Font_2,daedric_font
 
@@ -35,13 +41,19 @@ Unlike vanilla Morrowind, OpenMW directly supports TrueType (``.ttf``) fonts. Th
 OpenMW has build-in TrueType fonts: MysticCards, DemonicLetters and DejaVuLGCSansMono, which are used by default.
 TrueType fonts are configured via ``openmw.cfg`` too:
 
+.. code-block:: openmwcfg
+  :caption: openmw.cfg
+
   fallback=Fonts_Font_0,MysticCards
   fallback=Fonts_Font_2,DemonicLetters
 
 In this example, OpenMW will scan ``Fonts`` folder in data directories for ``.omwfont`` files.
 These files are XML files with schema provided by MyGUI. OpenMW uses ``.omwfont`` files which name (without extension) matches ``openmw.cfg`` entries.
 
-It is also possible to adjust the font size via ``settings.cfg`` file::
+It is also possible to adjust the font size via ``settings.cfg`` file:
+
+.. code-block:: ini
+  :caption: settings.cfg
 
   [GUI]
   font size = 16

docs/source/reference/modding/openmw-game-template.rst

@@ -36,7 +36,8 @@ and ``data=`` tells OpenMW what folders to look for meshes, textures, audio,
 and other assets. The required lines would look like this, but with the paths
 of course different on your system.
 
-.. code::
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     content=template.omwgame
     data="/home/someuser/example-suite/data"
@@ -51,7 +52,8 @@ you need to remove or comment out the following lines from ``openmw.cfg``.
 Not doing so will either produce errors or load Morrowind content, which you
 probably do not want when you are making your own game.
 
-.. code::
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     fallback-archive=Morrowind.bsa
     fallback-archive=Tribunal.bsa
@@ -70,8 +72,10 @@ are instead assigned through ``settings.cfg``. These models are player and NPC
 animations, and meshes for the sky. In ``settings.cfg`` used by your OpenMW
 install, add the following lines under the ``[Models]`` section.
 
-.. code::
+.. code-block:: ini
+    :caption: settings.cfg
 
+    [Models]
     xbaseanim = meshes/BasicPlayer.dae
     baseanim = meshes/BasicPlayer.dae
     xbaseanim1st = meshes/BasicPlayer.dae
@@ -103,7 +107,7 @@ need to be copied to ``resources/mygui`` folder found in your OpenMW installatio
 folder. Overwrite any files aready in this folder. These files provide the
 UI font, its definition, and some minor UI tweaks.
 
-.. code::
+.. code-block:: none
 
     openmw_box.skin.xml
     openmw_button.skin.xml

docs/source/reference/modding/paths.rst

@@ -134,7 +134,8 @@ This can't change until computers are able to read minds.
 Lines with options have an option name, then an equals sign (``=``), then an option value.
 Option names and values have leading and trailing whitespace trimmed, but whitespace within an option value is preserved - it's only removed if it's at the ends.
 This means that these are all equivalent:
-::
+
+.. code-block:: openmwcfg
 
     data=some/dir
         data=some/dir
@@ -226,7 +227,10 @@ Navigate to the OpenMW installation directory, and open the ``openmw.cfg`` file
 By default, this contains a warning at the top telling you that this is the local ``openmw.cfg`` and not to modify it.
 However, for this kind of install, it's okay to do so, so you can remove this warning.
 
-Change the start of the file from::
+Change the start of the file from:
+
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     # This is the local openmw.cfg file. Do not modify!
     # Modifications should be done on the user openmw.cfg file instead
@@ -243,7 +247,10 @@ Change the start of the file from::
     fallback=LightAttenuation_ConstantValue,0.0
     fallback=LightAttenuation_UseLinear,1
 
-to::
+to:
+
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     data-local=userdata/data
     user-data=userdata
@@ -274,7 +281,10 @@ Navigate to the OpenMW installation directory, and open the ``openmw.cfg`` file
 By default, this contains a warning at the top telling you that this is the local ``openmw.cfg`` and not to modify it.
 However, you'll need to make a small change to create this kind of install.
 
-Change the start of the file from::
+Change the start of the file from:
+
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     # This is the local openmw.cfg file. Do not modify!
     # Modifications should be done on the user openmw.cfg file instead
@@ -291,7 +301,10 @@ Change the start of the file from::
     fallback=LightAttenuation_ConstantValue,0.0
     fallback=LightAttenuation_UseLinear,1
 
-to::
+to:
+
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     # This is the local openmw.cfg file. Do not modify!
     # Modifications should be done on the user openmw.cfg file instead
@@ -330,7 +343,10 @@ From scratch
 Start by installing OpenMW in the usual way.
 Don't bother with first-time setup (i.e. telling it the location of an existing *Morrowind* installation).
 
-In the default configuration directory (see `Configuration files and log files`_), create a file called ``openmw.cfg`` containing just::
+In the default configuration directory (see `Configuration files and log files`_), create a file called ``openmw.cfg`` containing just
+
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     # select the game profile
     config=Morrowind
@@ -340,7 +356,10 @@ This will put the basic setup required to play *Morrowind* into a new ``Morrowin
 
 Next, come up with a name for the subprofile you'll create for your mod list.
 If you're following a modding guide, they've probably already given it a name, e.g. *Total Overhaul*, so that's the example we'll use.
-Add a line to the ``Morrowind/openmw.cfg`` with the profile name, e.g.::
+Add a line to the ``Morrowind/openmw.cfg`` with the profile name like this:
+
+.. code-block:: openmwcfg
+    :caption: Morrowind/openmw.cfg
 
     # select the mod list profile
     config=Total Overhaul
@@ -356,7 +375,10 @@ The ones in the ``Morrowind`` directory are used for all profiles for *Morrowind
 The ones in the ``Morrowind/Total Overhaul`` directory are only used for the *Total Overhaul* profile, so you can set up that mod list and any settings it requires here, and they won't affect any other profiles you set up later.
 Making changes within the launcher will affect these files and leave all the others alone.
 
-If you want the *Total Overhaul* profile to keep its saved games etc. in a dedicated location instead of mixing them in with ones from another profile, you can add a ``user-data=…`` line to your ``Morrowind/Total Overhaul/openmw.cfg``, e.g.::
+If you want the *Total Overhaul* profile to keep its saved games etc. in a dedicated location instead of mixing them in with ones from another profile, you can add a ``user-data=…`` line to your ``Morrowind/Total Overhaul/openmw.cfg``, like this:
+
+.. code-block:: openmwcfg
+    :caption: Morrowind/Total Overhaul/openmw.cfg
 
     # put saved games in a saves directory next to this file
     user-data=.
@@ -377,12 +399,18 @@ You'll now have an empty directory e.g. at ``Documents\My Games\OpenMW\Original`
 Next, move all the files that were already in the default configuration directory to the profile directory you just made.
 Afterwards, the default configuration directory should only contain the profile directory you made.
 
-Create a new ``openmw.cfg`` file in the default configuration directory containing::
+Create a new ``openmw.cfg`` file in the default configuration directory containing:
+
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     # select the profile
     config=Original
 
-In the ``openmw.cfg`` in the profile directory, add these lines::
+In the ``openmw.cfg`` in the profile directory, add these lines:
+
+.. code-block:: openmwcfg
+    :caption: openmw.cfg
 
     data-local=data
     user-data=.
@@ -402,9 +430,11 @@ Passing arguments on the command line lets you avoid this.
 
 The basic idea is that you need to pass ``--replace config`` to ignore the configuration directories that the engine would have loaded because they were specified in ``openmw.cfg`` files, and pass each one you want to use instead with ``--config <directory path here>``.
 
-E.g. if you've got a profile called *Morrowind* in your default configuration directory, and it's got a *Total Overhaul* subprofile, you could load it by running::
+E.g. if you've got a profile called *Morrowind* in your default configuration directory, and it's got a *Total Overhaul* subprofile, you could load it by running:
 
-    openmw --replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"
+.. code-block:: console
+
+    $ openmw --replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"
 
 You can put this command into a script or shortcut and use it to easily launch OpenMW with that profile.
 
@@ -422,7 +452,9 @@ On Windows, you can create a desktop shortcut to run this command with these ste
 * At the end of that field, add the arguments for the profile you want, e.g. ``--replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"``.
 * Press *Apply* or *OK* to save the changes, and test the shortcut by double-clicking it.
 
-On most Linux distros, you can create a ``.desktop`` file like this::
+On most Linux distros, you can create a ``.desktop`` file like this:
+
+.. code-block:: desktop
 
 	[Desktop Entry]
 	Type=Application

docs/source/reference/modding/texture-modding/convert-bump-mapped-mods.rst

@@ -2,24 +2,9 @@
 Normal maps from Morrowind to OpenMW
 ====================================
 
-- `General introduction to normal map conversion`_
-    - `OpenMW normal-mapping`_
-    - `Activating normal-mapping shaders in OpenMW`_
-    - `Morrowind bump-mapping`_
-    - `MGE XE normal-mapping`_
-- `Converting PeterBitt's Scamp Replacer`_ (Mod made for the MGE XE PBR prototype)
-    - `Tutorial - MGE`_
-- `Converting Lougian's Hlaalu Bump mapped`_ (Morrowind's bump-mapping, part 1: *without* custom models)
-    - `Tutorial - Morrowind, Part 1`_
-- `Converting Apel's Various Things - Sacks`_ (Morrowind's bump-mapping, part 2: *with* custom models)
-    - `Tutorial - Morrowind, Part 2`_
-
 General introduction to normal map conversion
 ---------------------------------------------
 
-:Authors: Joakim (Lysol) Berg, Alexei (Capo) Dobrohotov
-:Updated: 2020-03-03
-
 This page has general information and tutorials on how normal-mapping works in OpenMW and how you can make mods using
 the old environment-mapped bump-mapping technique (such as `Netch Bump mapped`_ and `Hlaalu Bump mapped`_, and maybe the most
 (in)famous one to previously give shiny rocks in OpenMW, the mod `On the Rocks`_!, featured in MGSO and Morrowind Rebirth) work better in OpenMW.
@@ -58,7 +43,8 @@ Activating normal-mapping shaders in OpenMW
 Before normal (and specular and parallax) maps can show up in OpenMW, their auto-detection needs to be turned on in
 settings.cfg_-file. Add these rows where it would make sense:
 
-::
+.. code-block:: ini
+  :caption: settings.cfg
 
   [Shaders]
   auto use object normal maps = true
@@ -81,7 +67,8 @@ are processed which makes bump-mapped models look a bit better,
 can make use of the gloss map channel in the bump map and can apply bump-mapping to skinned models.
 Add this to settings.cfg_-file:
 
-::
+.. code-block:: ini
+  :caption: settings.cfg
 
   [Shaders]
   apply lighting to environment maps = true
@@ -117,9 +104,6 @@ Converting PeterBitt's Scamp Replacer
 -------------------------------------
 **Mod made for the MGE XE PBR prototype**
 
-:Authors: Joakim (Lysol) Berg
-:Updated: 2016-11-11
-
 So, let's say you've found out that PeterBitt_ makes awesome models and textures featuring physically based rendering
 (PBR) and normal maps. Let's say that you tried to run his `PBR Scamp Replacer`_ in OpenMW and that you were greatly
 disappointed when the normal map didn't seem to work. Lastly, let's say you came here, looking for some answers.
@@ -161,9 +145,6 @@ Converting Lougian's Hlaalu Bump mapped
 ---------------------------------------
 **Mod made for Morrowind's bump-mapping, without custom models**
 
-:Authors: Joakim (Lysol) Berg, Alexei (Capo) Dobrohotov
-:Updated: 2020-03-03
-
 Converting normal maps made for the Morrowind's bump-mapping can be really easy or a real pain,
 depending on a few circumstances. In this tutorial, we will look at a very easy,
 although in some cases a bit time-consuming, example.
@@ -192,9 +173,6 @@ Converting Apel's Various Things - Sacks
 ----------------------------------------
 **Mod made for Morrowind bump-mapping, with custom models**
 
-:Authors: Joakim (Lysol) Berg, Alexei (Capostrophic) Dobrohotov
-:Updated: 2020-03-03
-
 In part one of this tutorial, we converted a mod that only included modified Morrowind model (``.nif``)
 files so that the bump maps could be loaded as normal maps.
 We ignored those model files since they are not needed with OpenMW. In this tutorial however,

docs/source/reference/modding/texture-modding/texture-basics.rst

@@ -55,7 +55,10 @@ Simply create the textures with appropriate naming convention
 the normal map would have to be called foo_n.dds).
 To enable this automatic use based on filename pattern,
 you will have to add the following to your
-`settings.cfg </source/reference/modding/paths>`_ file::
+`settings.cfg </source/reference/modding/paths>`_ file:
+
+.. code-block:: ini
+  :caption: settings.cfg
 
   [Shaders]
   auto use object normal maps = true
@@ -92,7 +95,10 @@ For example, if you wanted to add specular mapping to a terrain layer called roc
 you would copy this texture to a new file called rock_diffusespec.dds,
 and then edit its alpha channel to set the specular intensity.
 
-The relevant settings are::
+The relevant settings are
+
+.. code-block:: ini
+  :caption: settings.cfg
 
   [Shaders]
   auto use terrain normal maps = true