From 52e213485a389392a0fb5713f35ebccbec09530c Mon Sep 17 00:00:00 2001
From: Florian Spreckelsen <f.spreckelsen@indiscale.com>
Date: Mon, 26 Aug 2024 14:04:01 +0200
Subject: [PATCH] DOC: Move converters documentation to subdirectory
---
README_SETUP.md | 35 ++++++++++++++++++-
src/doc/README_SETUP.md | 34 ------------------
src/doc/cfood.rst | 2 +-
src/doc/concepts.rst | 2 +-
.../{converters.rst => converters/index.rst} | 14 ++++----
src/doc/index.rst | 2 +-
6 files changed, 45 insertions(+), 44 deletions(-)
mode change 120000 => 100644 README_SETUP.md
delete mode 100644 src/doc/README_SETUP.md
rename src/doc/{converters.rst => converters/index.rst} (98%)
diff --git a/README_SETUP.md b/README_SETUP.md
deleted file mode 120000
index d478016e..00000000
--- a/README_SETUP.md
+++ /dev/null
@@ -1 +0,0 @@
-src/doc/README_SETUP.md
\ No newline at end of file
diff --git a/README_SETUP.md b/README_SETUP.md
new file mode 100644
index 00000000..32f0bb89
--- /dev/null
+++ b/README_SETUP.md
@@ -0,0 +1,34 @@
+# Getting started with the CaosDB Crawler #
+
+## Installation
+see INSTALL.md
+
+## Run Unit Tests
+
+1. Install additional dependencies:
+ - h5py
+2. Run `pytest unittests`.
+
+## Documentation ##
+We use sphinx to create the documentation. Docstrings in the code should comply
+with the Googly style (see link below).
+
+Build documentation in `src/doc` with `make doc`. Note that for the
+automatic generation of the complete API documentation, it is
+necessary to first install this library with all its optional
+dependencies, i.e., `pip install .[h5-crawler,spss]`.
+
+### Requirements ###
+
+- `sphinx`
+- `sphinx-autoapi`
+- `recommonmark`
+- `sphinx-rtd-theme`
+
+### How to contribute ###
+
+- [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
+- [Google Style Python Docstrings 2nd reference](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings)
+- [References to other documentation](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#role-external)
+
+
diff --git a/src/doc/README_SETUP.md b/src/doc/README_SETUP.md
deleted file mode 100644
index 32f0bb89..00000000
--- a/src/doc/README_SETUP.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Getting started with the CaosDB Crawler #
-
-## Installation
-see INSTALL.md
-
-## Run Unit Tests
-
-1. Install additional dependencies:
- - h5py
-2. Run `pytest unittests`.
-
-## Documentation ##
-We use sphinx to create the documentation. Docstrings in the code should comply
-with the Googly style (see link below).
-
-Build documentation in `src/doc` with `make doc`. Note that for the
-automatic generation of the complete API documentation, it is
-necessary to first install this library with all its optional
-dependencies, i.e., `pip install .[h5-crawler,spss]`.
-
-### Requirements ###
-
-- `sphinx`
-- `sphinx-autoapi`
-- `recommonmark`
-- `sphinx-rtd-theme`
-
-### How to contribute ###
-
-- [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
-- [Google Style Python Docstrings 2nd reference](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings)
-- [References to other documentation](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#role-external)
-
-
diff --git a/src/doc/cfood.rst b/src/doc/cfood.rst
index 07431af0..51c39278 100644
--- a/src/doc/cfood.rst
+++ b/src/doc/cfood.rst
@@ -183,7 +183,7 @@ in a vairable with the same name (as it is the case for other Records).
Transform Functions
-------------------
You can use transform functions to alter variable values that the crawler consumes (e.g. a string
-that was matched with a reg exp). See :doc:`Converter Documentation<converters>`.
+that was matched with a reg exp). See :doc:`Converter Documentation<converters/index>`.
You can define your own transform functions by adding the the same way you add custom converters:
diff --git a/src/doc/concepts.rst b/src/doc/concepts.rst
index 77073185..4070aeff 100644
--- a/src/doc/concepts.rst
+++ b/src/doc/concepts.rst
@@ -34,7 +34,7 @@ existing StructureElements, Converters create a tree of StructureElements.
.. image:: img/converter.png
:height: 170
-See the chapter :std:doc:`Converters<converters>` for details.
+See the chapter :std:doc:`Converters<converters/index>` for details.
Relevant sources in:
diff --git a/src/doc/converters.rst b/src/doc/converters/index.rst
similarity index 98%
rename from src/doc/converters.rst
rename to src/doc/converters/index.rst
index 84acf4fe..c81f8e0f 100644
--- a/src/doc/converters.rst
+++ b/src/doc/converters/index.rst
@@ -5,7 +5,7 @@ Converters treat a StructureElement and during this process create a number of n
StructureElements: the children of the initially treated StructureElement. Thus by treatment of
existing StructureElements, Converters create a tree of StructureElements.
-.. image:: img/converter.png
+.. image:: ../img/converter.png
:height: 170
Each StructureElement in the tree has a set of properties, organized as
@@ -112,7 +112,7 @@ list valued property to the Report Record.
There are a number of transform functions that are defined by default (see
``src/caoscrawler/default_transformers.yml``). You can define custom transform functions by adding
-them to the cfood definition (see :doc:`CFood Documentation<cfood>`).
+them to the cfood definition (see :doc:`CFood Documentation<../cfood>`).
Standard Converters
@@ -297,7 +297,7 @@ property ``b`` with values "a", "b" and "c", and an ``author``
property which references an ``author`` with a ``full_name`` property
with value "Silvia Scientist":
-.. image:: img/properties-from-dict-records-author.png
+.. image:: ../img/properties-from-dict-records-author.png
:height: 210
Note how the different dictionary keys are handled differently
@@ -331,7 +331,7 @@ so that now, a ``Person`` record with a ``full_name`` property with
value "Silvia Scientist" is created as the value of the ``author``
property:
-.. image:: img/properties-from-dict-records-person.png
+.. image:: ../img/properties-from-dict-records-person.png
:height: 200
For the time being, only the parents of the referenced record can be
@@ -565,8 +565,10 @@ The basic syntax for adding a custom converter to a definition file is:
package: <python>.<module>.<name>
converter: <PythonClassName>
-The Converters section can be either put into the first or the second document of the cfood yaml file.
-It can be also part of a single-document yaml cfood file. Please refer to :doc:`the cfood documentation<cfood>` for more details.
+The Converters section can be either put into the first or the second
+document of the cfood yaml file. It can be also part of a
+single-document yaml cfood file. Please refer to :doc:`the cfood
+documentation<../cfood>` for more details.
Details:
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 8a02ec62..a72389b1 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -10,7 +10,7 @@ CaosDB-Crawler Documentation
Getting started<getting_started/index>
Tutorials<tutorials/index>
Concepts<concepts>
- Converters<converters>
+ Converters<converters/index>
CFoods (Crawler Definitions)<cfood>
Macros<macros>
How to upgrade<how-to-upgrade>
--
GitLab