[doc] reorganization and link fixes for mkdocs

Author: knopers8

core/integration/README.md

@@ -5,7 +5,7 @@ A plugin can register a set of callback which can be invoked upon defined enviro
 
 ## Plugin system overview
 
-All plugins should implement the [`Plugin`](/core/integration/plugin.go) interface.
+All plugins should implement the [`Plugin`](https://github.com/AliceO2Group/Control/blob/master/core/integration/plugin.go) interface.
 See the existing plugins for examples.
 
 In order to have the plugin loaded by the AliECS, one has to:

docs/CONTRIBUTING.md

@@ -46,4 +46,18 @@ Gomega/Ginkgo tests are preferred, but other style of tests are also welcome.
 
 - Add documentation for new features.
 
-- Your contribution will be reviewed by the project maintainers once the PR is marked as ready for review.
+- Your contribution will be reviewed by the project maintainers once the PR is marked as ready for review.
+
+## Documentation guidelines
+
+The markdown documentation is aimed to be browsed on GitHub, but it also on the aggregated [FLP documentation](https://alice-flp.docs.cern.ch) based on [MkDocs](https://www.mkdocs.org/).
+Consequently, any changes in the documentation structure should be reflected in the Table of Contents in the main README.md, as well as `mkdocs.yml` and `mkdocs.yml`.
+
+The AliECS MkDocs documentation is split into two aforementioned files to follow the split between "Products" and "Developers" tabs in the FLP documentation.
+The `mkdocs-dev.yml` uses a symlink `aliecs-dev` to `aliecs` directory to avoid complaints about duplicated site names.
+
+Because of the dual target of the documentation, the points below are important to keep in mind:
+
+- Absolute paths in links to other files do not always work, they should be avoided.
+- When referencing source files in the repository, use full URIs to GitHub.
+- In MkDocs layouts, one cannot reference specific sections within markdown files. Only links to entire markdown files are possible.

docs/building.md

@@ -84,6 +84,6 @@ You should find several executables including `o2control-core`, `o2control-execu
 
 For subsequent builds (after the first one), plain `make` (instead of `make all`) is sufficient. See the [Makefile reference](makefile_reference.md) for more information.
 
-If you wish to also build the process control library and/or plugin, see [the OCC readme](/occ/README.md).
+If you wish to also build the process control library and/or plugin, see [the OCC readme](../occ/README.md).
 
 This build of AliECS can be run locally and connected to an existing O²/FLP Suite cluster by passing a `--mesosUrl` parameter. If you do this, remember to `systemctl stop o2-aliecs-core` on the head node, in order to stop the core that came with the O²/FLP Suite and use your own.

docs/development.md

@@ -4,7 +4,7 @@ Generated API documentation is available on [pkg.go.dev](https:///pkg.go.dev/git
 
 The release log is managed via [GitHub](https://github.com/AliceO2Group/Control/releases/).
 
-Bugs go to [JIRA](https://alice.its.cern.ch/jira/browse/OCTRL).
+Bugs go to [JIRA](https://its.cern.ch/jira/projects/OCTRL/issues).
 
 ## Release Procedure
 

docs/handbook/configuration.md

@@ -199,7 +199,7 @@ for examples of call roles that reference a variety of integration plugins.
 The state machine callback moments are exposed to the AliECS workflow template interface and can be used as triggers or synchronization points for integration plugin function calls. The `call` block can be used for this purpose, with similar syntax to the `task` block used for controllable tasks. Its fields are as follows.
 
 * `func` - mandatory, it parses as an [`antonmedv/expr`](https://github.com/antonmedv/expr) expression that corresponds to a call to a function that belongs to an integration plugin object (e.g. `bookkeeping.StartOfRun()`, `dcs.EndOfRun()`, etc.).
-* `trigger` - mandatory, the expression at `func` will be executed once the state machine reaches this moment. For possible values, see [State machine triggers](/docs/handbook/operation_order.md#state-machine-triggers)
+* `trigger` - mandatory, the expression at `func` will be executed once the state machine reaches this moment. For possible values, see [State machine triggers](operation_order.md#state-machine-triggers)
 * `await` - optional, if absent it defaults to the same as `trigger`, the expression at `func` needs to finish by this moment, and the state machine will block until `func` completes.
 * `timeout` - optional, Go `time.Duration` expression, defaults to `30s`, the maximum time that `func` should take. The value is provided to the plugin via `varStack["__call_timeout"]` and the plugin should implement a timeout mechanism. The ECS will not abort the call upon reaching the timeout value!
 * `critical` - optional, it defaults to `true`, if `true` then a failure or timeout for `func` will send the environment state machine to `ERROR`.

docs/handbook/operation_order.md

@@ -1,7 +1,7 @@
 # Environment operation order
 
 This chapter attempts to document the order of important operations done during environment transitions.
-Since AliECS is an evolving system, the information presented here might be out-of-date, thus please refer to event handling in [core/environment/environment.go](https://github.com/AliceO2Group/Control/blob/master/core/environment/environment.go) and plugin calls in [ControlWorkflows/workflows/readout-dataflow.yaml](https://github.com/AliceO2Group/ControlWorkflows/blob/master/workflows/readout-dataflow.yaml) for the ultimate source of truth.
+Since AliECS is an evolving system, the information presented here might be out-of-date, thus please refer to event handling in [environment.go][https://github.com/AliceO2Group/Control/blob/master/core/environment/environment.go) and plugin calls in [ControlWorkflows/workflows/readout-dataflow.yaml](https://github.com/AliceO2Group/ControlWorkflows/blob/master/workflows/readout-dataflow.yaml) for the ultimate source of truth.
 Also, please report to the ECS developers any inaccuracies.
 
 ## State machine triggers

docs/metrics.md

@@ -59,7 +59,7 @@ ECS and aliecs.run are values.
 6) space - divides fields and timestamp
 7) timestamp - (optional) int64 value of unix timestamp in ns
 
-In order to provide support for this format we introduced Metric structure in [common/monitoring/metric.go](../common/monitoring/metric.go).
+In order to provide support for this format we introduced Metric structure in [common/monitoring/metric.go](https://github.com/AliceO2Group/Control/blob/master/common/monitoring/metric.go).
 Following code shows how to create a Metric with `measurement` as measurement name,
 one tag `tag1=val1` and field `field1=42u`:
 
@@ -70,7 +70,7 @@ m.SetFieldUInt64("field1", 42)
 ```
 
 However we also need to be able to store metrics, so these can be scraped correctly.
-This mechanism is implemented in [common/monitoring/monitoring.go](../common/monitoring/monitoring.go).
+This mechanism is implemented in [common/monitoring/monitoring.go](https://github.com/AliceO2Group/Control/blob/master/common/monitoring/monitoring.go).
 Metrics endpoint is run by calling `Run(port, endpointName)`. As this method is blocking
 it is advised to call it from `goroutine`. After this method is called we can than send
 metrics via methods `Send` and `SendHistogrammable`. If you want to send simple metrics
@@ -92,7 +92,7 @@ Example for this use-case is duration of some function,
 eg. measure sending batch of messages. If we want the best coverage of metrics possible
 we can combine both of these to measure amount of messages send per batch and
 also measurement duration of the send. For example in code you can take a look actual
-actual code in [writer.go](../common/event/writer.go) where we are sending multiple
+actual code in [writer.go](https://github.com/AliceO2Group/Control/blob/master/common/event/writer.go) where we are sending multiple
 fields per metric and demonstrate full potential of these metrics.
 
 Previous code example will result in following metrics to be reported:
@@ -203,7 +203,7 @@ if different points, but creating statistical report as mentioned in previous pa
 ### Event loop
 
 In order to send metrics from unlimited amount of goroutines, we need to have
-robust and thread-safe mechanism. It is implemented in [common/monitoring/monitoring.go](../common/monitoring/monitoring.go)
+robust and thread-safe mechanism. It is implemented in [common/monitoring/monitoring.go](https://github.com/AliceO2Group/Control/blob/master/common/monitoring/monitoring.go)
 as event loop (`eventLoop`) that reads data from two buffered channels (`metricsChannel` and `metricsHistosChannel`)
 with one goroutine. Apart from reading messages from these two channels event loop also handles
 scraping requests from `http.Server` endpoint. As the http endpoint is called by a
@@ -219,8 +219,8 @@ which are consumed by event loop.
 In order to correctly implement behaviour described in the part about Aggregation
 we use the same implementation in two container aggregating objects
 `MetricsAggregate`, `MetricsReservoirSampling` implemented in files
-[common/monitoring/metricsaggregate.go](../common/monitoring/metricsaggregate.go)
-and [metricsreservoirsampling.go](../common/monitoring/metricsreservoirsampling.go)
+[common/monitoring/metricsaggregate.go](https://github.com/AliceO2Group/Control/blob/master/common/monitoring/metricsaggregate.go)
+and [metricsreservoirsampling.go](https://github.com/AliceO2Group/Control/blob/master/common/monitoring/metricsreservoirsampling.go)
 in the same directory. The implementation is done as different buckets
 in map with distinct keys (`metricsBuckets`). These keys need to be unique
 according to the timestamp and tags. We use struct `key` composed

hacking/COG.md

@@ -44,11 +44,11 @@ In production, AliECS will manage and push all configuration to active tasks, bu
 
 Every task still has their own configuration file, with paths such as `/etc/flp.d/qc/*.json` for QualityControl and `/home/flp/readout.cfg` for Readout. These paths can be edited by the user, and any changes affect all newly launched instances of the task.
 
-All configuration file paths used by tasks can be found in the task descriptors of the workflow configuration repository in use. For more information on workflow configuration repositories, see [the `coconut repository` reference](/coconut/doc/coconut_repository.md). The default workflow configuration repository which comes pre-loaded with AliECS is accessible at [AliceO2Group/ControlWorkflows](https://github.com/AliceO2Group/ControlWorkflows) (all task descriptor files are found in the `tasks` directory).
+All configuration file paths used by tasks can be found in the task descriptors of the workflow configuration repository in use. For more information on workflow configuration repositories, see [the `coconut repository` reference](../coconut/doc/coconut_repository.md). The default workflow configuration repository which comes pre-loaded with AliECS is accessible at [AliceO2Group/ControlWorkflows](https://github.com/AliceO2Group/ControlWorkflows) (all task descriptor files are found in the `tasks` directory).
 
 * **modify an existing workflow or task?**
 
-You are free to keep as many workflow configuration repositories as you wish in your AliECS instance. For more information on workflow configuration repositories, see [the `coconut repository` reference](/coconut/doc/coconut_repository.md).
+You are free to keep as many workflow configuration repositories as you wish in your AliECS instance. For more information on workflow configuration repositories, see [the `coconut repository` reference](../coconut/doc/coconut_repository.md).
 
 Changes to a configuration repository are immediately available after running `coconut repo refresh`. There is no support in the AliECS GUI at this time.
 

mkdocs-dev.yml

@@ -0,0 +1,12 @@
+site_name: aliecs-dev
+
+nav:
+    - 'Contributing': '/docs/CONTRIBUTING.md'
+    - 'Development': '/docs/development.md'
+    - 'Package pkg.go.dev': 'https://pkg.go.dev/github.com/AliceO2Group/Control'
+    - 'Building': '/docs/building.md'
+    - 'Makefile reference': '/docs/makefile_reference.md'
+    - 'Component Configuration': '/docs/handbook/appconfiguration.md'
+    - 'Running': 'docs/running.md'
+    - 'Metrics': '/docs/metrics.md'
+    - 'OCC API debugging': '/docs/using_grpcc_occ.md'

mkdocs.yml

@@ -2,31 +2,29 @@ site_name: aliecs
 
 nav:
     - 'Handbook':
-        - Introduction: handbook/index.md
-        - Overview: handbook/overview.md
-        - Basic Concepts: handbook/concepts.md
-        - Environment Operation Order: handbook/operation_order.md
-        - Configuration:
-            - Workflow Configuration: handbook/configuration.md
-            - Apricot Usage: './apricot/docs/apricot.md'
-            - Apricot HTTP API: './apricot/docs/apricot_http_service.md'
-        - Interfaces:
-            - AliECS gRPC API: apidocs_aliecs.md
-            - Apricot gRPC API: apidocs_apricot.md
-            - OCC gRPC API (Protobuf based): apidocs_occ.md
-            - Kafka: kafka.md
-        - Workflow Variables: '../controlworkflows/README.md'
-    - 'Command Reference':
-        - coconut:
-            - Overview: './coconut/README.md'
-            - coconut: './coconut/doc/coconut.md'
-            - coconut about: './coconut/doc/coconut_about.md'
-            - coconut configuration: './coconut/doc/coconut_configuration.md'
-            - coconut environment: './coconut/doc/coconut_environment.md'
-            - coconut info: './coconut/doc/coconut_info.md'
-            - coconut repository: './coconut/doc/coconut_repository.md'
-            - coconut role: './coconut/doc/coconut_role.md'
-            - coconut task: './coconut/doc/coconut_task.md'
-            - coconut template: './coconut/doc/coconut_template.md'
-        - peanut: './occ/peanut/README.md'
-    - 'FAQ': faq.md
+        - 'Introduction': 'docs/handbook/introduction.md'
+        - 'Basic Concepts': 'docs/handbook/concepts.md'
+        - 'Design Overview': 'docs/handbook/overview.md'
+        - 'Workflow and Task Config.': 'docs/handbook/configuration.md'
+        - 'Environment Operation Order': 'docs/handbook/operation_order.md'
+        - 'Workflow Variables': '../controlworkflows'
+    - 'Component reference':
+        - 'AliECS GUI': 'hacking/COG.md'
+        - 'AliECS core':
+            - 'Integrated Services': 'core/integration/README.md'
+            - 'Protocol': 'docs/apidocs_aliecs.md'
+        - 'coconut':
+            - 'Overview': 'coconut/README.md'
+            - 'Command Ref.': 'coconut/doc/coconut.md'
+        - 'apricot':
+            - 'Overview': 'apricot/README.md'
+            - 'HTTP Service': 'apricot/docs/apricot_http_service.md'
+            - 'Protocol': 'docs/apidocs_apricot.md'
+            - 'Command Ref.': 'apricot/docs/apricot.md'
+        - 'occ':
+            - 'Overview': 'occ/README.md'
+            - 'Example': 'occ/occlib/examples/dummy-process/README.md'
+            - 'Protocol': 'docs/apidocs_occ.md'
+        - 'peanut':
+            - 'Overview': 'occ/peanut/README.md'
+        - 'Event Service': 'docs/kafka.md'