Merge pull request #2447 from myk002/myk_doc_fixup

Fix and organize docs

ci/authors-rst.py

@@ -11,9 +11,9 @@ def main():
             info += ' %s %s:' % (k, kwargs[k])
         print('line %i:%s %s' % (line, info, msg))
         if os.environ.get('GITHUB_ACTIONS'):
-            print('::error file=docs/Authors.rst,line=%i::%s %s' % (line, info.lstrip(), msg))
+            print('::error file=docs/about/Authors.rst,line=%i::%s %s' % (line, info.lstrip(), msg))
         success[0] = False
-    with open('docs/Authors.rst', 'rb') as f:
+    with open('docs/about/Authors.rst', 'rb') as f:
         lines = list(map(lambda line: line.decode('utf8').replace('\n', ''), f.readlines()))
 
         if lines[1].startswith('='):

ci/lint-ignore.txt

@@ -10,9 +10,14 @@ plugins/stonesense/*.txt
 # Generated files
 *.pb.h
 build*/*
-docs/_*
+docs/changelogs/*
 docs/html/*
 docs/pdf/*
+docs/pseudoxml/*
+docs/tags/*
+docs/text/*
+docs/tools/*
+docs/xml/*
 library/include/df/*
 
 # Dependencies that we don't control

docs/NEWS.rst

@@ -24,4 +24,4 @@ Older Changelogs
 ================
 Are kept in a separate file:  `History`
 
-.. that's ``docs/History.rst``, if you're reading the raw text.
+.. that's ``docs/about/History.rst``, if you're reading the raw text.

docs/about/index.rst

@@ -7,7 +7,7 @@ These pages contain information about the general DFHack project.
 .. toctree::
    :maxdepth: 1
 
-   /docs/NEWS
-   /docs/Authors
+   /docs/about/Authors
    /LICENSE
-   /docs/Removed
+   /docs/about/Removed
+   /docs/NEWS

docs/api/index.rst

@@ -1,6 +1,6 @@
-====================
-DFHack API reference
-====================
+===================
+DFHack API concepts
+===================
 
 .. toctree::
     :maxdepth: 1

docs/changelog.txt

@@ -1,7 +1,7 @@
 === Scroll down for changes
 
 ===[[[
-The text below is included in docs/Documentation.rst - see that file for more details on the changelog setup.
+The text below is included in docs/dev/Documentation.rst - see that file for more details on the changelog setup.
 This is kept in this file as a quick syntax reference.
 
 ===help

docs/dev/Binpatches.rst

@@ -155,7 +155,7 @@ gui/assign-rack
 Bind to a key (the example config uses :kbd:`P`), and activate when viewing a weapon
 rack in the :kbd:`q` mode.
 
-.. image:: images/assign-rack.png
+.. image:: /docs/images/assign-rack.png
 
 This script is part of a group of related fixes to make the armory storage
 work again. The existing issues are:

docs/dev/Contributing.rst

@@ -92,7 +92,7 @@ General contribution guidelines
   compiles. Our CI should catch anything that fails to build, but checking in
   advance can sometimes let you know of any issues sooner.
 * Update documentation when applicable - see `docs-standards` for details.
-* Update ``changelog.txt`` and ``docs/Authors.rst`` when applicable. See
+* Update ``docs/changelog.txt`` and ``docs/about/Authors.rst`` when applicable. See
   `build-changelog` for more information on the changelog format.
 * Submit ideas and bug reports as :issue:`issues on GitHub <>`.
   Posts in the forum thread can easily get missed or forgotten.

docs/dev/Lua API.rst

@@ -2,9 +2,9 @@
 
 .. _lua-api:
 
-##############
-DFHack Lua API
-##############
+########################
+DFHack Lua API Reference
+########################
 
 DFHack has extensive support for
 the Lua_ scripting language, providing access to:

docs/dev/index.rst

@@ -0,0 +1,21 @@
+========================
+DFHack development guide
+========================
+
+These are pages relevant to people developing for DFHack.
+
+.. toctree::
+   :maxdepth: 1
+
+   /docs/dev/Dev-intro
+   /docs/dev/Compile
+   /docs/dev/Contributing
+   /docs/dev/Documentation
+   /docs/api/index
+   /docs/dev/Lua API
+   /docs/dev/overlay-dev-guide
+   /docs/dev/Structures-intro
+   /docs/dev/Memory-research
+   /docs/dev/Binpatches
+   /docs/dev/Remote
+   /docs/NEWS-dev

docs/dev/overlay-dev-guide.rst

@@ -16,17 +16,17 @@ screen. If you need very specific low-level control, those APIs might be the
 right choice for you. However, here are some reasons you might want to implement
 an overlay widget instead:
 
-1. You can draw directly to an existing viewscreen instead of creating an
+#. You can draw directly to an existing viewscreen instead of creating an
     entirely new screen on the viewscreen stack. This allows the original
     viewscreen to continue processing uninterrupted and keybindings bound to
     that viewscreen will continue to function. This was previously only
     achievable by C++ plugins.
 
-1. You'll get a free UI for enabling/disabling your widget and repositioning it
+#. You'll get a free UI for enabling/disabling your widget and repositioning it
     on the screen. Widget state is saved for you and is automatically restored
     when the game is restarted.
 
-1. You don't have to manage the C++ interposing logic yourself and can focus on
+#. You don't have to manage the C++ interposing logic yourself and can focus on
     the business logic, writing purely in Lua if desired.
 
 In general, if you are writing a plugin or script and have anything you'd like

docs/guides/index.rst

@@ -7,9 +7,8 @@ These pages are detailed guides covering DFHack tools.
 .. toctree::
    :maxdepth: 1
 
-   /docs/guides/examples-guide
-   /docs/guides/overlay-dev-guide
    /docs/guides/modding-guide
+   /docs/guides/examples-guide
    /docs/guides/quickfort-library-guide
    /docs/guides/quickfort-user-guide
    /docs/guides/quickfort-alias-guide

docs/index-dev.rst

@@ -1,20 +0,0 @@
-========================
-DFHack development guide
-========================
-
-These are pages relevant to people developing for DFHack.
-
-.. toctree::
-   :maxdepth: 1
-
-   /docs/Dev-intro
-   /docs/Contributing
-   /docs/Compile
-   /docs/NEWS-dev
-   /docs/Lua API
-   /docs/Remote
-   /docs/api/index
-   /docs/Documentation
-   /docs/Structures-intro
-   /docs/Memory-research
-   /docs/Binpatches

index.rst

@@ -30,5 +30,5 @@ User Manual
    /docs/Core
    /docs/Tools
    /docs/guides/index
-   /docs/index-dev
-   /docs/index-about
+   /docs/dev/index
+   /docs/about/index