new docs format, fixes cli tests

DiamondLightSource · Jun 7, 2023 · 7ce7293 · 7ce7293
1 parent 0419cb3
commit 7ce7293
Show file tree

Hide file tree

Showing 24 changed files with 107 additions and 154 deletions.
diff --git a/README.md b/README.md
@@ -3,36 +3,6 @@ xchembku
 
 XChem Business Knowledge Unit.  Service, Client, API, persistent store.
 
-Installation
------------------------------------------------------------------------
-::
-
-    pip install xchembku
-
-    xchembku --version
-
-Documentation
------------------------------------------------------------------------
-
-See https://www.cs.diamond.ac.uk/xchembku for more detailed documentation.
-
-Building and viewing the documents locally::
-
-    git clone git+https://gitlab.diamond.ac.uk/scisoft/bxflow/xchembku.git 
-    cd xchembku
-    virtualenv /scratch/$USER/venv/xchembku
-    source /scratch/$USER/venv/xchembku/bin/activate 
-    pip install -e .[dev]
-    make -f .xchembku/Makefile validate_docs
-    browse to file:///scratch/$USER/venvs/xchembku/build/html/index.html
-
-Topics for further documentation:
-
-- TODO list of improvements
-- change log
-
-
-..
-    Anything below this line is used when viewing README.rst and will be replaced
-    when included in index.rst
+Database service for other XChem Lifesupport services.
 
+For documentation see: https://diamondlightsource.github.io/xchembku
diff --git a/docs/conf.py b/docs/conf.py
@@ -55,7 +55,7 @@
 
 # If true, Sphinx will warn about all references where the target cannot
 # be found.
-nitpicky = True
+nitpicky = False
 
 # A list of (type, target) tuples (by default empty) that should be ignored when
 # generating warnings in "nitpicky mode". Note that type should include the
@@ -197,4 +197,4 @@ def setup(app):
     app.connect("source-read", ultimateReplace)
 
 
-# dae_devops_fingerprint c1c571c112da8688ea81070cffde5401
+# dae_devops_fingerprint 555976e9a952e0d19b731360f4d76fc4
diff --git a/docs/user/explanations/22-developing.rst → docs/explanations/conventions.rst b/docs/user/explanations/22-developing.rst → docs/explanations/conventions.rst
@@ -1,4 +1,4 @@
 ..
     Use the file automatically generated by dae-devops.
     
-.. include:: ../../../.dae-devops/docs/developing.rst
+.. include:: ../../.dae-devops/docs/conventions.rst
diff --git a/docs/explanations/docs_structure.rst b/docs/explanations/docs_structure.rst
@@ -0,0 +1,4 @@
+..
+    Use the file automatically generated by dae-devops.
+    
+.. include:: ../../.dae-devops/docs/docs_structure.rst
diff --git a/docs/explanations/index.rst b/docs/explanations/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+Explanations
+============
+
+Explanation, or discussions, clarify and illuminate a particular topic. They broaden the documentation's coverage of a topic.
+
+.. toctree::
+
+    docs_structure
+    conventions
+    todo
diff --git a/docs/explanations/todo.rst b/docs/explanations/todo.rst
@@ -0,0 +1,7 @@
+TODO
+=======================================================================
+
+- Remove matplotlib from imports done by mib2hdfConvert package to decrease load time and debug volume.
+- Make sure we can collect and process mib files which are not in a material subdirectory.
+- Add unit tests for the mib_convert task.
+
diff --git a/docs/user/explanations/23-testing.rst → docs/how-to/developing.rst b/docs/user/explanations/23-testing.rst → docs/how-to/developing.rst
@@ -1,4 +1,4 @@
 ..
     Use the file automatically generated by dae-devops.
     
-.. include:: ../../../.dae-devops/docs/testing.rst
+.. include:: ../../.dae-devops/docs/developing.rst
diff --git a/docs/user/explanations/24-devops.rst → docs/how-to/devops.rst b/docs/user/explanations/24-devops.rst → docs/how-to/devops.rst
@@ -1,4 +1,4 @@
 ..
     Use the file automatically generated by dae-devops.
     
-.. include:: ../../../.dae-devops/docs/devops.rst
+.. include:: ../../.dae-devops/docs/devops.rst
diff --git a/...user/how-to/01-installing_development.rst → docs/how-to/documenting.rst b/...user/how-to/01-installing_development.rst → docs/how-to/documenting.rst
@@ -1,4 +1,4 @@
 ..
     Use the file automatically generated by dae-devops.
     
-.. include:: ../../../.dae-devops/docs/installing.rst
+.. include:: ../../.dae-devops/docs/documenting.rst
diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+How-to Guides
+=============
+
+How-to guides take the reader through the steps required to solve a real-world problem.
+Practical step-by-step guides for the more experienced user.
+
+.. toctree::
+
+    installing
+    developing
+    testing
+    documenting
+    devops
+
diff --git a/docs/how-to/installing.rst b/docs/how-to/installing.rst
@@ -0,0 +1,5 @@
+..
+    Use the file automatically generated by dae-devops.
+    
+.. include:: ../../.dae-devops/docs/installing.rst
+
diff --git a/docs/how-to/testing.rst b/docs/how-to/testing.rst
@@ -0,0 +1,4 @@
+..
+    Use the file automatically generated by dae-devops.
+    
+.. include:: ../../.dae-devops/docs/testing.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,23 +1,14 @@
-.. include:: ../README.rst
-    :end-before: when included in index.rst
+xchembku
+=======================================================================
 
-Source repository
------------------------------------------------------------------------
+XChem Business Knowledge Unit.  Service, Client, API, persistent store.
 
-${git_url}/${repository_name}
-
-Documentation
------------------------------------------------------------------------
-
-.. grid:: 2
-
-    .. grid-item-card:: :material-regular:`person;4em`
-        :link: user/index
-        :link-type: doc
-
-        The User Guide contains documentation on how to install and use the software.
+Database service for other XChem Lifesupport services.
 
 .. toctree::
-    :hidden:
+    :titlesonly:
 
-    user/index
+    tutorials/index
+    how-to/index
+    explanations/index
+    reference/index
diff --git a/docs/reference/classes.rst b/docs/reference/classes.rst
@@ -0,0 +1,7 @@
+Classes
+=======================================================================
+
+DirectPoll Collector
+-----------------------------------------------------------------------
+.. autoclass:: xchembku_lib.datafaces.direct.Direct
+    :members:
diff --git a/docs/user/reference/api/command_line.rst → docs/reference/command_line.rst b/docs/user/reference/api/command_line.rst → docs/reference/command_line.rst
@@ -1,9 +1,9 @@
 Command Line
 =======================================================================
 
-dls-multiconf
+xchembku
 -----------------------------------------------------------------------
 .. argparse:: 
-    :module: dls_multiconf_lib.__main__
+    :module: xchembku_lib.__main__
     :func: get_parser
-    :prog: dls-multiconf
+    :prog: xchembku
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -0,0 +1,13 @@
+:orphan:
+
+Reference
+=========
+
+Reference guides are technical descriptions of the machinery and how to operate it.
+
+.. toctree::
+    :maxdepth: 2
+
+    command_line
+    classes
+    modules
diff --git a/docs/reference/modules.rst b/docs/reference/modules.rst
@@ -0,0 +1,7 @@
+Functions
+=======================================================================
+
+Version Functions
+------------------------------------------------------------------------
+.. automodule:: xchembku_lib.version
+    :members:
diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+Tutorials
+=========
+
+Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. 
+They are what your project needs in order to show a beginner that they can achieve something with it.
+
+.. toctree::
+
+    tbd
diff --git a/docs/user/tutorials/tbd.rst → docs/tutorials/tbd.rst b/docs/user/tutorials/tbd.rst → docs/tutorials/tbd.rst
@@ -1,4 +1,4 @@
-TBD
+TBD Tutorial
 =======================================================================
 
 TBD
diff --git a/docs/user/explanations/25-docs-structure.rst b/docs/user/explanations/25-docs-structure.rst
diff --git a/docs/user/index.rst b/docs/user/index.rst
diff --git a/docs/user/reference/api.rst b/docs/user/reference/api.rst
diff --git a/docs/user/reference/api/classes.rst b/docs/user/reference/api/classes.rst
diff --git a/docs/user/reference/api/modules.rst b/docs/user/reference/api/modules.rst