Merge pull request #700 from kordejong/gh583

Improve documentation

document/doc/CMakeLists.txt

@@ -19,57 +19,6 @@ doxygen_add_docs(
  )
 
 set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/${DOXYGEN_OUTPUT_DIRECTORY})
-# set(AUTODOC2_PACKAGE_DIR ../../${LUE_BUILD_PYTHON_PACKAGE_DIR})
-
-
-# set(SPHINX_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
-# set(SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
-# set(SPHINX_INDEX_FILE ${SPHINX_BUILD_DIR}/index.html)
-#
-# file(GLOB_RECURSE sphinx_sources LIST_DIRECTORIES False *.rst)
-#
-# configure_file(conf.py.in conf.py @ONLY)
-#
-# add_custom_command(
-# OUTPUT ${SPHINX_INDEX_FILE}
-# COMMAND
-# ${CMAKE_COMMAND}
-# -E env "PYTHONPATH=${PROJECT_BINARY_DIR}/${LUE_INSTALL_PYTHON_PACKAGE_DIR}/..:$ENV{PYTHONPATH}"
-# ${SPHINX_BUILD_EXECUTABLE} -b html
-# -c ${CMAKE_CURRENT_BINARY_DIR}
-# -Dbreathe_projects.LUE=${DOXYGEN_OUTPUT_DIR}/xml
-# ${SPHINX_SOURCE_DIR} ${SPHINX_BUILD_DIR}
-# DEPENDS
-# doxygen_doc
-# ${sphinx_sources}
-# MAIN_DEPENDENCY
-# ${CMAKE_CURRENT_BINARY_DIR}/conf.py)
-#
-# add_custom_target(sphinx_doc DEPENDS ${SPHINX_INDEX_FILE})
-#
-# # TODO Make this depend on the generation of the docs. They must be ready to copy.
-# # install(
-# # DIRECTORY
-# # ${SPHINX_BUILD_DIR}
-# # DESTINATION ${CMAKE_INSTALL_DOCDIR}
-# # COMPONENT lue_development
-# # )
-
-
-# # https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
-# add_custom_target(python_api
-# VERBATIM
-# COMMAND
-# ${CMAKE_COMMAND}
-# -E env "SPHINX_APIDOC_OPTIONS=members,undoc-members,show-inheritance,inherited-members"
-# ${SPHINX_APIDOC_EXECUTABLE}
-# --force
-# --separate
-# --module-first
-# -d 1
-# -o ${CMAKE_CURRENT_BINARY_DIR}/reference/python/api
-# ${CMAKE_BINARY_DIR}/${LUE_BUILD_PYTHON_PACKAGE_DIR}
-# )
 
 configure_file(
  _config.yml.in
@@ -78,19 +27,16 @@ configure_file(
 )
 
 foreach(name IN ITEMS
- about/project.md
  about/license.md
+ about/project.md
  about/publication.md
  about/related.md
  about/release.md
- contribute/index.md
  contribute/documentation.md
+ contribute/index.md
  contribute/release.md
  example/index.md
  index.md
- install/conda.md
- install/index.md
- install/source.md
  manual/data_model/concept.md
  manual/data_model/format.md
  manual/data_model/index.md
@@ -99,32 +45,40 @@ foreach(name IN ITEMS
  manual/framework/index.md
  manual/framework/python/index.md
  manual/framework/scalability.md
- manual/view/index.md
  manual/glossary.md
+ manual/index.md
+ manual/install/conda.md
+ manual/install/index.md
+ manual/install/source.md
+ manual/view/index.md
+ pcraster/index.md
+ pcraster/port.md
+ pcraster/status.md
+ quick_start/cpp.md
+ quick_start/index.md
+ quick_start/python.md
  reference/algorithm/clump.md
  reference/algorithm/index.md
  # reference/cpp/dataset.md
  reference/cpp/index.md
- # reference/python/data_model/index.rst
+ reference/index.md
  # reference/python/data_model/hdf5/index.rst
+ # reference/python/data_model/index.rst
  # reference/python/framework/index.rst
  reference/python/index.md
  references.bib
- short_description.md
- pcraster/port.md
- pcraster/status.md
  reference/utility/index.md
  reference/utility/lue_calculate.md
  reference/utility/lue_scalability.md
  reference/utility/lue_translate.md
  reference/utility/lue_validate.md
  reference/utility/lue_view.md
+ short_description.md
  _toc.yml
 )
  configure_file(${name} ${name} COPYONLY)
 endforeach()
 
-
 foreach(name IN ITEMS
  data_model/doc/index.md
  doc/index.md
@@ -136,6 +90,8 @@ foreach(name IN ITEMS
  framework/algorithm/doc/policy/range.md
  framework/algorithm/doc/template.md
 
+ framework/doc/test/index.md
+
  framework/doc/howto/index.md
  framework/doc/howto/add_local_operation.md
 
@@ -148,6 +104,7 @@ foreach(name IN ITEMS
  framework/algorithm/doc/grouped_operation/global_operation.md
  framework/algorithm/doc/grouped_operation/routing_operation.md
  framework/algorithm/doc/grouped_operation/mathematical_operation.md
+ framework/algorithm/doc/grouped_operation/array_operation.md
  framework/algorithm/doc/grouped_operation/random_number_operation.md
 
  framework/partitioned_array/doc/index.md

document/doc/_toc.yml

@@ -1,68 +1,63 @@
-# Table of contents
-# Learn more at https://jupyterbook.org/customize/toc.html
+# https://jupyterbook.org/en/stable/structure/toc.html
 
 format: jb-book
 root: index
 parts:
- - caption: Manual
+ - caption: User
  chapters:
- - file: install/index.md
- sections:
- - file: install/conda.md
- - file: install/source.md
- - file: manual/data_model/index.md
+
+ - file: quick_start/index.md
  sections:
- - file: manual/data_model/concept.md
- - file: manual/data_model/format.md
- - file: manual/framework/index.md
+ - file: quick_start/python.md
+ - file: quick_start/cpp.md
+
+ - file: manual/index.md
  sections:
- - file: manual/framework/python/index.md
- - file: manual/framework/cpp/index.md
- - file: manual/framework/execute.md
- - file: manual/framework/scalability.md
- - file: manual/view/index.md
- - file: manual/glossary.md
- - caption: Reference
- chapters:
- - file: reference/python/index.md
- # sections:
- # - file: reference/python/data_model/index.rst
- # - file: reference/python/data_model/hdf5/index.rst
- # - file: reference/python/framework/index.rst
- # - file: reference/python/api/lue.rst
- # - url: file:///genindex.html
- # title: genindex
- # - url: file:///py-modindex.html
- # title: py-modindex
- # - url: file:///search.html
- # title: search
- # - file: reference/python/apidocs/index.rst
- # sections:
- # - file: reference/python/data_model/hdf5/file.rst
- # chapters:
- # - file: genindex.html
- - file: reference/cpp/index.md
- # sections:
- # - file: reference/cpp/dataset.md
- - file: reference/utility/index.md
+ - file: manual/install/index.md
+ sections:
+ - file: manual/install/conda.md
+ - file: manual/install/source.md
+ - file: manual/data_model/index.md
+ sections:
+ - file: manual/data_model/concept.md
+ - file: manual/data_model/format.md
+ - file: manual/framework/index.md
+ sections:
+ - file: manual/framework/python/index.md
+ - file: manual/framework/cpp/index.md
+ - file: manual/framework/execute.md
+ - file: manual/framework/scalability.md
+ - file: manual/view/index.md
+ - file: manual/glossary.md
+
+ - file: reference/index.md
  sections:
- - file: reference/utility/lue_calculate.md
- - file: reference/utility/lue_scalability.md
- - file: reference/utility/lue_translate.md
- - file: reference/utility/lue_validate.md
- - file: reference/utility/lue_view.md
- - file: reference/algorithm/index.md
+ - file: reference/python/index.md
+ - file: reference/cpp/index.md
+ - file: reference/utility/index.md
+ sections:
+ - file: reference/utility/lue_calculate.md
+ - file: reference/utility/lue_scalability.md
+ - file: reference/utility/lue_translate.md
+ - file: reference/utility/lue_validate.md
+ - file: reference/utility/lue_view.md
+ - file: reference/algorithm/index.md
+ sections:
+ - file: reference/algorithm/clump.md
+
+ - file: pcraster/index.md
  sections:
- - file: reference/algorithm/clump.md
- - caption: PCRaster
- chapters:
- - file: pcraster/port.md
- - file: pcraster/status.md
- - caption: Development
+ - file: pcraster/port.md
+ - file: pcraster/status.md
+
+ - caption: Developer
  chapters:
+
  - file: contribute/index.md
- - file: contribute/documentation.md
- - file: contribute/release.md
+ sections:
+ - file: contribute/documentation.md
+ - file: contribute/release.md
+
  - file: source/doc/index.md
  sections:
  - file: source/data_model/doc/index.md
@@ -86,13 +81,17 @@ parts:
  - file: source/framework/algorithm/doc/grouped_operation/zonal_operation.md
  - file: source/framework/algorithm/doc/grouped_operation/global_operation.md
  - file: source/framework/algorithm/doc/grouped_operation/routing_operation.md
+ - file: source/framework/algorithm/doc/grouped_operation/array_operation.md
  - file: source/framework/algorithm/doc/grouped_operation/mathematical_operation.md
  - file: source/framework/algorithm/doc/grouped_operation/random_number_operation.md
+ - file: source/framework/doc/test/index.md
  - file: source/framework/doc/howto/index.md
  sections:
  - file: source/framework/doc/howto/add_local_operation.md
+
  - caption: About
  chapters:
+
  - file: about/project.md
  - file: about/release.md
  - file: example/index.md

document/doc/about/project.md

@@ -1,6 +1,17 @@
 (doc-about-project)=
 # Project
 
+```{include} short_description.md
+```
+
+:::{margin}
+LUE is an acronym for "Life, the Universe and Everything". It is pronounced as the French pronounce the name
+Louis (`LU-EE`).
+:::
+
+The LUE data model is described in more detail in {cite}`DeBakker:2017` and {cite}`DeJong:2019`. Details
+about the LUE framework can be found in {cite}`DeJong:2021` and {cite}`DeJong:2022`.
+
 LUE is the result of multiple research projects performed by the [Computational
 Geography](https://www.computationalgeography.org) group at Utrecht University in The Netherlands. One of the
 focus areas of this group is to improve on the concepts and design of environmental modelling frameworks, with

document/doc/index.md

@@ -1,26 +1,5 @@
 # LUE
 
-:::{margin}
-LUE is an acronym for "Life, the Universe and Everything". It is pronounced as the French pronounce the name
-Louis (`LU-EE`).
-:::
-
-```{include} short_description.md
-```
-
-The LUE data model is described in more detail in {cite}`DeBakker:2017` and {cite}`DeJong:2019`. Details
-about the LUE framework can be found in {cite}`DeJong:2021` and {cite}`DeJong:2022`.
-
 :::{warning}
 This documentation is work in progress. It is improved continuously, but nowhere near being complete.
 :::
-
-The documentation is split into several parts:
-
-| | |
-| --- | --- |
-| Manual | General information about LUE. Start here if you are new to the software. |
-| Reference | Details required to be able to use LUE. |
-| PCRaster | Information for model developers interested in porting their PCRaster model to use LUE. |
-| Development | Information for software developers interested in contributing to LUE. |
-| About | Information about the project that doesn't fit in the other parts. |

document/doc/pcraster/index.md

@@ -0,0 +1 @@
+# PCRaster

document/doc/quick_start/cpp.md

@@ -0,0 +1,15 @@
+# Game of Life in C++
+
+## Install
+
+TODO
+
+
+## Implement
+
+TODO
+
+
+## Execute
+
+TODO

document/doc/quick_start/index.md

@@ -0,0 +1,5 @@
+# Quick start
+
+Here, you will find just enough information to get started with using LUE. It is targetted at model
+developers. We will be implementing [Conway's Game of
+Life](https://en.wikipedia.org/wiki/Conway's_Game_of_Life) and execute it in parallel, using a single process.

document/doc/quick_start/python.md

@@ -0,0 +1,14 @@
+# Game of Life in Python
+
+## Install
+```bash
+conda install -c conda-forge lue
+```
+
+See also [](#install-conda).
+
+
+## Implement
+
+
+## Execute

source/doc/index.md

@@ -1,5 +1,5 @@
 (source-lue)=
-# Source
+# Source code
 
 The LUE software contains two main parts: code related to the physical [](#source-lue-data-model) and code
 related to the [framework](#source-lue-framework) for environmental modelling.

source/framework/algorithm/doc/group.dox

@@ -25,3 +25,7 @@
 /*!
  @defgroup random_number_operation Random number operations
 */
+
+/*!
+ @defgroup array_operation Array operations
+*/

source/framework/algorithm/doc/grouped_operation/array_operation.md

@@ -0,0 +1,8 @@
+(source-framework-algorithm-array)=
+# Array operations
+
+
+```{eval-rst}
+.. doxygengroup:: array_operation
+ :content-only:
+```

source/framework/algorithm/doc/grouped_operation/index.md

@@ -17,3 +17,4 @@
 - [Zonal operations](#source-framework-algorithm-zonal)
 - [Global operations](#source-framework-algorithm-global)
 - [Routing operations](#source-framework-algorithm-routing)
+- [Array operations](#source-framework-algorithm-array)