docs in standard layout

David Erb · David Erb · commit c40e828b6a9d · 2023-06-07T15:02:43.000+01:00
diff --git a/.dae-devops/project.yaml b/.dae-devops/project.yaml
@@ -2,7 +2,7 @@
 primary:
   repository_name: dls-normsql
   package_name: dls_normsql
-  one_line_description: "Normalized API over various sql libraries."
+  one_line_description: "Normalized API over various sql libraries for consistency across multiple projects."
   author:
     name: David Erb
     email: david.erb@diamond.ac.uk
diff --git a/README.md b/README.md
@@ -0,0 +1,5 @@
+dls-normsql
+=======================================================================
+
+Normalized API over various sql libraries for consistency across multiple projects.
+
diff --git a/README.rst b/README.rst
diff --git a/docs/explanations/conventions.rst b/docs/explanations/conventions.rst
@@ -0,0 +1,4 @@
+..
+    Use the file automatically generated by dae-devops.
+    
+.. 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/how-to/developing.rst b/docs/how-to/developing.rst
@@ -0,0 +1,4 @@
+..
+    Use the file automatically generated by dae-devops.
+    
+.. include:: ../../.dae-devops/docs/developing.rst
diff --git a/docs/how-to/devops.rst b/docs/how-to/devops.rst
@@ -0,0 +1,4 @@
+..
+    Use the file automatically generated by dae-devops.
+    
+.. include:: ../../.dae-devops/docs/devops.rst
diff --git a/docs/how-to/documenting.rst b/docs/how-to/documenting.rst
@@ -0,0 +1,4 @@
+..
+    Use the file automatically generated by dae-devops.
+    
+.. 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,6 @@
+..
+    Use the file automatically generated by dae-devops.
+    
+.. include:: ../../.dae-devops/docs/installing.rst
+
+Since this package is just a library, the command line doesn't do anything else besides print the version.
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,9 +1,12 @@
+dls-normsql
+=======================================================================
 
-.. include:: ../README.rst
-    :end-before: when included in index.rst
+Normalized API over various sql libraries for consistency across multiple projects.
 
 .. toctree::
-    :caption: API-caption
-    :hidden:
+    :titlesonly:
 
-    api/index
+    tutorials/index
+    how-to/index
+    explanations/index
+    reference/index
diff --git a/docs/reference/classes.rst b/docs/reference/classes.rst
diff --git a/docs/reference/command_line.rst b/docs/reference/command_line.rst
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
diff --git a/docs/reference/modules.rst b/docs/reference/modules.rst
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/tutorials/tbd.rst b/docs/tutorials/tbd.rst
@@ -0,0 +1,4 @@
+TBD Tutorial
+=======================================================================
+
+TBD
diff --git a/pyproject.toml b/pyproject.toml
@@ -13,7 +13,7 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3.10",
 ]
-description = "Normalized API over various sql libraries."
+description = "Normalized API over various sql libraries for consistency across multiple projects."
 dependencies = ["dls-utilpack", "aiosqlite", "aiomysql", "cryptography"]
 dynamic = ["version"]
 license.file = "LICENSE"
@@ -100,4 +100,4 @@ source = ["src", "**/site-packages/"]
 [tool.tox]
 legacy_tox_ini = "[tox]\nskipsdist=True\n\n[testenv:{pre-commit,mypy,pytest,docs}]\n# Don't create a virtualenv for the command, requires tox-direct plugin\ndirect = True\npassenv = *\nallowlist_externals = \n    pytest \n    pre-commit\n    mypy\n    sphinx-build\n    sphinx-autobuild\ncommands =\n    pytest: pytest {posargs}\n    mypy: mypy src tests {posargs}\n    pre-commit: pre-commit run --all-files {posargs}\n    docs: sphinx-{posargs:build -EW --keep-going} -T docs build/html\n"
 
-# dae_devops_fingerprint df8767613c8b867ee1ddb91dd8b71fca
+# dae_devops_fingerprint aec34b4646849a704b0974693e0148cc

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +..
 +    Use the file automatically generated by dae-devops.
++
 +.. include:: ../../.dae-devops/docs/conventions.rst