diff --git a/README.md b/README.md index 29f6448..51b7052 100644 --- 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 \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index ae952f6..654974a 100644 --- 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 b/docs/explanations/conventions.rst similarity index 53% rename from docs/user/explanations/22-developing.rst rename to docs/explanations/conventions.rst index 735ac5c..c1b5c81 100644 --- a/docs/user/explanations/22-developing.rst +++ b/docs/explanations/conventions.rst @@ -1,4 +1,4 @@ .. Use the file automatically generated by dae-devops. -.. include:: ../../../.dae-devops/docs/developing.rst \ No newline at end of file +.. include:: ../../.dae-devops/docs/conventions.rst \ No newline at end of file diff --git a/docs/explanations/docs_structure.rst b/docs/explanations/docs_structure.rst new file mode 100644 index 0000000..18c92dc --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/explanations/index.rst b/docs/explanations/index.rst new file mode 100644 index 0000000..0e5e221 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/explanations/todo.rst b/docs/explanations/todo.rst new file mode 100644 index 0000000..15ef74f --- /dev/null +++ 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. + \ No newline at end of file diff --git a/docs/user/explanations/23-testing.rst b/docs/how-to/developing.rst similarity index 54% rename from docs/user/explanations/23-testing.rst rename to docs/how-to/developing.rst index 35336eb..5964239 100644 --- a/docs/user/explanations/23-testing.rst +++ b/docs/how-to/developing.rst @@ -1,4 +1,4 @@ .. Use the file automatically generated by dae-devops. -.. include:: ../../../.dae-devops/docs/testing.rst \ No newline at end of file +.. include:: ../../.dae-devops/docs/developing.rst \ No newline at end of file diff --git a/docs/user/explanations/24-devops.rst b/docs/how-to/devops.rst similarity index 55% rename from docs/user/explanations/24-devops.rst rename to docs/how-to/devops.rst index f426f7a..334cc58 100644 --- a/docs/user/explanations/24-devops.rst +++ b/docs/how-to/devops.rst @@ -1,4 +1,4 @@ .. Use the file automatically generated by dae-devops. -.. include:: ../../../.dae-devops/docs/devops.rst \ No newline at end of file +.. include:: ../../.dae-devops/docs/devops.rst \ No newline at end of file diff --git a/docs/user/how-to/01-installing_development.rst b/docs/how-to/documenting.rst similarity index 53% rename from docs/user/how-to/01-installing_development.rst rename to docs/how-to/documenting.rst index d398810..cdb5964 100644 --- a/docs/user/how-to/01-installing_development.rst +++ b/docs/how-to/documenting.rst @@ -1,4 +1,4 @@ .. Use the file automatically generated by dae-devops. -.. include:: ../../../.dae-devops/docs/installing.rst \ No newline at end of file +.. include:: ../../.dae-devops/docs/documenting.rst \ No newline at end of file diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst new file mode 100644 index 0000000..21b92fc --- /dev/null +++ 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 + \ No newline at end of file diff --git a/docs/how-to/installing.rst b/docs/how-to/installing.rst new file mode 100644 index 0000000..2d4d929 --- /dev/null +++ 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 new file mode 100644 index 0000000..2cd284b --- /dev/null +++ b/docs/how-to/testing.rst @@ -0,0 +1,4 @@ +.. + Use the file automatically generated by dae-devops. + +.. include:: ../../.dae-devops/docs/testing.rst \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 7ae3783..92cd53a 100644 --- 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 new file mode 100644 index 0000000..ace1d38 --- /dev/null +++ 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 b/docs/reference/command_line.rst similarity index 71% rename from docs/user/reference/api/command_line.rst rename to docs/reference/command_line.rst index 85eeef3..af8716e 100644 --- a/docs/user/reference/api/command_line.rst +++ b/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 \ No newline at end of file diff --git a/docs/reference/index.rst b/docs/reference/index.rst new file mode 100644 index 0000000..88d9357 --- /dev/null +++ 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 new file mode 100644 index 0000000..3da473c --- /dev/null +++ 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 new file mode 100644 index 0000000..2af6711 --- /dev/null +++ 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 b/docs/tutorials/tbd.rst similarity index 82% rename from docs/user/tutorials/tbd.rst rename to docs/tutorials/tbd.rst index 0c0a16c..14489c4 100644 --- a/docs/user/tutorials/tbd.rst +++ b/docs/tutorials/tbd.rst @@ -1,4 +1,4 @@ -TBD +TBD Tutorial ======================================================================= TBD \ No newline at end of file diff --git a/docs/user/explanations/25-docs-structure.rst b/docs/user/explanations/25-docs-structure.rst deleted file mode 100644 index f25a09b..0000000 --- a/docs/user/explanations/25-docs-structure.rst +++ /dev/null @@ -1,18 +0,0 @@ -About the documentation ------------------------ - - :material-regular:`format_quote;2em` - - The Grand Unified Theory of Documentation - - -- David Laing - -There is a secret that needs to be understood in order to write good software -documentation: there isn't one thing called *documentation*, there are four. - -They are: *tutorials*, *how-to guides*, *technical reference* and *explanation*. -They represent four different purposes or functions, and require four different -approaches to their creation. Understanding the implications of this will help -improve most documentation - often immensely. - -`More information on this topic. `_ diff --git a/docs/user/index.rst b/docs/user/index.rst deleted file mode 100644 index 9e70993..0000000 --- a/docs/user/index.rst +++ /dev/null @@ -1,58 +0,0 @@ -User Guide -========== - -Documentation is split into four categories, also accessible from links in the side-bar. - -.. grid:: 2 - :gutter: 4 - - .. grid-item-card:: :material-regular:`directions_walk;3em` - - .. toctree:: - :caption: Tutorials - :maxdepth: 1 - - tutorials/tbd - - +++ - - Tutorials for installation and typical usage. New users start here. - - .. grid-item-card:: :material-regular:`directions;3em` - - .. toctree:: - :caption: How-to Guides - :maxdepth: 1 - - how-to/01-installing_development - - +++ - - Practical step-by-step guides for the more experienced user. - - .. grid-item-card:: :material-regular:`info;3em` - - .. toctree:: - :caption: Explanations - :maxdepth: 1 - - explanations/22-developing - explanations/23-testing - explanations/24-devops - explanations/25-docs-structure - - +++ - - Explanations of how the library works and why it works that way. - - .. grid-item-card:: :material-regular:`menu_book;3em` - - .. toctree:: - :caption: Reference - :maxdepth: 1 - - reference/api - - +++ - - Technical reference material including APIs and release notes. diff --git a/docs/user/reference/api.rst b/docs/user/reference/api.rst deleted file mode 100644 index 313507a..0000000 --- a/docs/user/reference/api.rst +++ /dev/null @@ -1,9 +0,0 @@ -API -======================================================================= - -.. toctree:: - :maxdepth: 1 - - api/command_line - api/classes - api/modules diff --git a/docs/user/reference/api/classes.rst b/docs/user/reference/api/classes.rst deleted file mode 100644 index d96d810..0000000 --- a/docs/user/reference/api/classes.rst +++ /dev/null @@ -1,5 +0,0 @@ -Classes -======================================================================= - -.. autoclass:: dls_multiconf_lib.multiconfs.Multiconfs - :members: diff --git a/docs/user/reference/api/modules.rst b/docs/user/reference/api/modules.rst deleted file mode 100644 index 8ec9804..0000000 --- a/docs/user/reference/api/modules.rst +++ /dev/null @@ -1,4 +0,0 @@ -Functions -======================================================================= -.. automodule:: dls_multiconf_lib.version - :members: