Attempt to workaround folding problem

doc/mkdocs.yml

@@ -3,6 +3,9 @@ theme: readthedocs
 
 docs_dir: source
 
+extra_css:
+  - css/extra.css
+
 nav:
   - 'index.md'
   - 'getting_the_module.md'
@@ -18,47 +21,47 @@ nav:
   - 'access_to_voxels_and_multithreading.md'
   - 'module_development.md'
   - 'changelog.md'
+  - '___.md'
   - 'API':
-    - 'Classes':
-      # <generated_class_list>
-      - api/FastNoiseLite.md
-      - api/FastNoiseLiteGradient.md
-      - api/Voxel.md
-      - api/VoxelBlockSerializer.md
-      - api/VoxelBoxMover.md
-      - api/VoxelBuffer.md
-      - api/VoxelColorPalette.md
-      - api/VoxelGenerator.md
-      - api/VoxelGeneratorFlat.md
-      - api/VoxelGeneratorGraph.md
-      - api/VoxelGeneratorHeightmap.md
-      - api/VoxelGeneratorImage.md
-      - api/VoxelGeneratorNoise.md
-      - api/VoxelGeneratorNoise2D.md
-      - api/VoxelGeneratorScript.md
-      - api/VoxelGeneratorWaves.md
-      - api/VoxelLibrary.md
-      - api/VoxelLodTerrain.md
-      - api/VoxelMesher.md
-      - api/VoxelMesherBlocky.md
-      - api/VoxelMesherCubes.md
-      - api/VoxelMesherDMC.md
-      - api/VoxelMesherTransvoxel.md
-      - api/VoxelNode.md
-      - api/VoxelRaycastResult.md
-      - api/VoxelServer.md
-      - api/VoxelStream.md
-      - api/VoxelStreamBlockFiles.md
-      - api/VoxelStreamFile.md
-      - api/VoxelStreamRegionFiles.md
-      - api/VoxelStreamScript.md
-      - api/VoxelTerrain.md
-      - api/VoxelTool.md
-      - api/VoxelToolBuffer.md
-      - api/VoxelToolTerrain.md
-      - api/VoxelViewer.md
-      - api/VoxelVoxLoader.md
-      # </generated_class_list>
+    # <generated_class_list>
+    - api/FastNoiseLite.md
+    - api/FastNoiseLiteGradient.md
+    - api/Voxel.md
+    - api/VoxelBlockSerializer.md
+    - api/VoxelBoxMover.md
+    - api/VoxelBuffer.md
+    - api/VoxelColorPalette.md
+    - api/VoxelGenerator.md
+    - api/VoxelGeneratorFlat.md
+    - api/VoxelGeneratorGraph.md
+    - api/VoxelGeneratorHeightmap.md
+    - api/VoxelGeneratorImage.md
+    - api/VoxelGeneratorNoise.md
+    - api/VoxelGeneratorNoise2D.md
+    - api/VoxelGeneratorScript.md
+    - api/VoxelGeneratorWaves.md
+    - api/VoxelLibrary.md
+    - api/VoxelLodTerrain.md
+    - api/VoxelMesher.md
+    - api/VoxelMesherBlocky.md
+    - api/VoxelMesherCubes.md
+    - api/VoxelMesherDMC.md
+    - api/VoxelMesherTransvoxel.md
+    - api/VoxelNode.md
+    - api/VoxelRaycastResult.md
+    - api/VoxelServer.md
+    - api/VoxelStream.md
+    - api/VoxelStreamBlockFiles.md
+    - api/VoxelStreamFile.md
+    - api/VoxelStreamRegionFiles.md
+    - api/VoxelStreamScript.md
+    - api/VoxelTerrain.md
+    - api/VoxelTool.md
+    - api/VoxelToolBuffer.md
+    - api/VoxelToolTerrain.md
+    - api/VoxelViewer.md
+    - api/VoxelVoxLoader.md
+    # </generated_class_list>
   - 'Serialization formats':
     - 'specs/block_format.md'
     - 'specs/region_format_v2.md'

doc/source/___.md

@@ -0,0 +1,11 @@
+
+Nothing to see here.
+
+This file is an expression of my lack of motivation to make Mkdocs work better with ReadTheDocs. It sits there only to separate a bit more the API section from the rest of the doc.
+
+The API class list is at "top level" (actually second level) and does not fold, because no more than 2 file-levels are supported by the theme provided by ReadTheDocs. If the class files were placed at third level, folding works for them, but breaks the rest of the nav.
+
+Allowing custom themes on ReadTheDocs could allow to fix it, but it's [officially not supported](https://github.com/readthedocs/readthedocs.org/issues/978#issuecomment-285212453).
+I considered switching to Sphinx, but it's too complicated in comparison to Mkdocs. Switching all the existing docs and scripts to use ReStructuredText is also a lot of work. Sphinx claims to support Markdown too but my attempts at using it failed.
+
+So for now... have a bit of space.

doc/source/css/extra.css

@@ -0,0 +1,4 @@
+/* Without this, top-level items are barely recognizable from second-level */
+.caption {
+    color: #5599ff;
+}

doc/tools/build.py

@@ -99,11 +99,12 @@ def update_mkdocs_file(mkdocs_config_fpath, md_classes_dir):
                 in_generated_section = False
             else:
                 continue
-        processed_lines.append(line)
         if "<generated_class_list>" in line:
             in_generated_section = True
-            for cf in class_files:
-                processed_lines.append("      - " + cf + "\n")
+            indent = line[:line.find('#')]
+            processed_lines.append(line)
+            for class_file in class_files:
+                processed_lines.append(indent + "- " + class_file + "\n")
 
     yml = "".join(processed_lines)
     with open(mkdocs_config_fpath, 'w', encoding='utf-8') as f: