Merge pull request #963 from PowerGridModel/feature/minor-format-docs4

Add markdownlint formatting checks

Author: mgovers

.github/workflows/check-code-quality.yml

@@ -61,6 +61,12 @@ jobs:
           sudo apt-get update && sudo apt-get install -y clang-format-18
           find . -regex '.*\.\(h\|c\|cpp\|hpp\|cc\|cxx\)' -exec clang-format-18 -style=file -i {} \;
 
+      - name: Install and run markdownlint
+        run: |
+          npm install -g markdownlint-cli
+          echo "Running markdownlint"
+          markdownlint --fix .
+
       - name: If needed raise error
         run: |
 

.markdownlint.yaml

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+# MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md001.md
+MD001: false
+
+# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md013.md
+MD013: false
+  # # Number of characters
+  # line_length: 80
+  # # Number of characters for headings
+  # heading_line_length: 80
+  # # Number of characters for code blocks
+  # code_block_line_length: 80
+  # # Include code blocks
+  # code_blocks: true
+  # # Include tables
+  # tables: true
+  # # Include headings
+  # headings: true
+  # # Strict length checking
+  # strict: false
+  # # Stern length checking
+  # stern: false
+
+# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md024.md
+MD024: false
+
+# MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md033.md
+MD033: false
+
+# MD040/fenced-code-language : Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md040.md
+MD040: false
+
+# MD041/first-line-heading/first-line-h1 : First line in a file should be a top-level heading : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md041.md
+MD041: false
+
+# MD042/no-empty-links : No empty links : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md042.md
+MD042: false
+
+# MD045/no-alt-text : Images should have alternate text (alt text) : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md045.md
+MD045: false
+
+# MD051/link-fragments : Link fragments should be valid : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md051.md
+MD051: false
+
+# MD056/table-column-count : Table column counts should match : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md056.md
+MD056: false

.pre-commit-config.yaml

@@ -41,3 +41,8 @@ repos:
     hooks:
       - id: clang-format
         types_or: [ c++, c ]
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.44.0
+    hooks:
+    - id: markdownlint
+      args: ["--fix"]

README.md

@@ -68,7 +68,7 @@ To install the library from source, refer to the [Build Guide](https://power-gri
 
 ## Examples
 
-Please refer to [Examples](https://github.com/PowerGridModel/power-grid-model-workshop/tree/main/examples) for more detailed examples for power flow and state estimation. 
+Please refer to [Examples](https://github.com/PowerGridModel/power-grid-model-workshop/tree/main/examples) for more detailed examples for power flow and state estimation.
 Notebooks for validating the input data and exporting input/output data are also included.
 
 ## License
@@ -77,14 +77,14 @@ This project is licensed under the Mozilla Public License, version 2.0 - see [LI
 
 ## Licenses third-party libraries
 
-This project includes third-party libraries, 
+This project includes third-party libraries,
 which are licensed under their own respective Open-Source licenses.
-SPDX-License-Identifier headers are used to show which license is applicable. 
+SPDX-License-Identifier headers are used to show which license is applicable.
 The concerning license files can be found in the [LICENSES](https://github.com/PowerGridModel/power-grid-model/tree/main/LICENSES) directory.
 
 ## Contributing
 
-Please read [CODE_OF_CONDUCT](https://github.com/PowerGridModel/.github/blob/main/CODE_OF_CONDUCT.md), [CONTRIBUTING](https://github.com/PowerGridModel/.github/blob/main/CONTRIBUTING.md), [PROJECT GOVERNANCE](https://github.com/PowerGridModel/.github/blob/main/GOVERNANCE.md) and [RELEASE](https://github.com/PowerGridModel/.github/blob/main/RELEASE.md) for details on the process 
+Please read [CODE_OF_CONDUCT](https://github.com/PowerGridModel/.github/blob/main/CODE_OF_CONDUCT.md), [CONTRIBUTING](https://github.com/PowerGridModel/.github/blob/main/CONTRIBUTING.md), [PROJECT GOVERNANCE](https://github.com/PowerGridModel/.github/blob/main/GOVERNANCE.md) and [RELEASE](https://github.com/PowerGridModel/.github/blob/main/RELEASE.md) for details on the process
 for submitting pull requests to us.
 
 Visit [Contribute](https://github.com/PowerGridModel/power-grid-model/contribute) for a list of good first issues in this repo.

docs/advanced_documentation/c-api.md

@@ -7,18 +7,18 @@ SPDX-License-Identifier: MPL-2.0
 # Use Power Grid Model through C API
 
 While many users use Python API for Power Grid Model.
-This library also provides a C API. 
-The main use case of C API is to integrate Power Grid Model into a non-Python application/library, namely, C, C++, JAVA, C#, etc. 
+This library also provides a C API.
+The main use case of C API is to integrate Power Grid Model into a non-Python application/library, namely, C, C++, JAVA, C#, etc.
 
-The C API consists of some 
+The C API consists of some
 {{ "[header files]({}/power_grid_model_c/power_grid_model_c/include)".format(gh_link_head_blob) }}
-and a dynamic library (`.so` or `.dll`) built by a 
+and a dynamic library (`.so` or `.dll`) built by a
 {{ "[cmake project]({}/power_grid_model_c/power_grid_model_c/CMakeLists.txt)".format(gh_link_head_blob) }}.
 Please refer to the [Build Guide](./build-guide.md) about how to build the library.
 
 You can refer to the [C API Reference](../api_reference/power-grid-model-c-api-reference.rst)
-for a detailed documentation of the API. 
-Please also have a look at an 
+for a detailed documentation of the API.
+Please also have a look at an
 {{ "[example]({}/power_grid_model_c_example/main.c)".format(gh_link_head_blob) }}
 of C program to use this C API.
 
@@ -37,7 +37,7 @@ and making it available to their binaries, e.g. by adding its location to `PATH`
 
 ## Opaque struct/pointer
 
-As a common C API practice, we use [opaque struct/pointer](https://en.wikipedia.org/wiki/Opaque_pointer) in the API. 
+As a common C API practice, we use [opaque struct/pointer](https://en.wikipedia.org/wiki/Opaque_pointer) in the API.
 The user creates the object by `PGM_create_*` function and release the object by `PGM_destroy_*` function.
 In other function calls, the user provide the relevant opaque pointer as the argument.
 The real memory layout of the object is unknown to the user.
@@ -50,21 +50,21 @@ Moreover, we might want to also retrieve some meta information from the calculat
 The C API uses a handle opaque object `PGM_Handle` to store all these kinds of error messages and information.
 You need to pass a handle pointer to most of the functions in the C API.
 
-For example, after calling `PGM_create_model`, you can use `PGM_error_code` and `PGM_error_message` 
+For example, after calling `PGM_create_model`, you can use `PGM_error_code` and `PGM_error_message`
 to check if there is error during the creation and the error message.
 
 If you are calling the C API in multiple threads, each thread should have its own handle object created by `PGM_create_handle`.
 
 ## Calculation options
 
-To execute a power grid calculation you need to specify many options, 
+To execute a power grid calculation you need to specify many options,
 e.g., maximum number of iterations, error tolerance, etc.
 We could have declared all the calculation options as individual arguments in the `PGM_calculate` function.
-However, due to the lack of default argument in C, 
+However, due to the lack of default argument in C,
 this would mean that the C API has a breaking change everytime we add a new option,
 which happends very often.
 
-To solve this issue, we use another opaque object `PGM_Options`. The user creates an object with default options by `PGM_create_options`. You can then specify individual options by `PGM_set_*`. 
+To solve this issue, we use another opaque object `PGM_Options`. The user creates an object with default options by `PGM_create_options`. You can then specify individual options by `PGM_set_*`.
 In the `PGM_calculate` function you need to pass a pointer to `PGM_Options`.
 In this way, we can ensure the API backwards compatibility.
 If we add a new option, it will get a default value in the `PGM_create_options` function.
@@ -77,7 +77,7 @@ For compatibility reasons, that format is dictated by the C API using the `PGM_m
 
 We define the following concepts in the data hierarchy:
 
-* Dataset: a collection of data buffers for a given purpose. 
+* Dataset: a collection of data buffers for a given purpose.
   At this moment, we have four dataset types: `input`, `update`, `sym_output`, `asym_output`.
 * Component: a data buffer with the representation of all attributes of a physical grid component in our [data model](../user_manual/components.md), e.g., `node`.
 * Attribute: a property of given component. For example, `u_rated` attribute of `node` is the rated voltage of the node.
@@ -126,7 +126,7 @@ Data buffers are almost always allocated and freed in the heap. We provide two w
 
 * You can use the function `PGM_create_buffer` and `PGM_destroy_buffer` to create and destroy buffer.
   In this way, the library is handling the memory (de-)allocation.
-* You can call some memory (de-)allocation function in your own code according to your platform, 
+* You can call some memory (de-)allocation function in your own code according to your platform,
   e.g., `aligned_alloc` and `free`.
   You need to first call `PGM_meta_*` functions to retrieve the size and alignment of a component.
 
@@ -141,10 +141,10 @@ Once you have the data buffer, you need to set or get attributes. We provide two
 
 * You can use the function `PGM_buffer_set_value` and `PGM_buffer_get_value` to get and set values.
 * You can do pointer cast directly on the buffer pointer, by shifting the pointer to proper offset
-  and cast it to a certain value type. 
+  and cast it to a certain value type.
   You need to first call `PGM_meta_*` functions to retrieve the correct offset.
 
-Pointer cast is generally more efficient and flexible because you are not calling into the 
+Pointer cast is generally more efficient and flexible because you are not calling into the
 dynamic library everytime. But it requires the user to retrieve the offset information first.
 Using the buffer helper function is more convenient but with some overhead.
 
@@ -153,7 +153,7 @@ Using the buffer helper function is more convenient but with some overhead.
 In the C API we have a function `PGM_buffer_set_nan` which sets all the attributes in a buffer to `NaN`.
 In the calculation core, if an optional attribute is `NaN`, it will use the default value.
 
-If you just want to set some attributes and keep everything else as `NaN`, 
+If you just want to set some attributes and keep everything else as `NaN`,
 calling `PGM_buffer_set_nan` before you set attribute is convenient.
 This is useful especially in `update` dataset because you do not always update all the mutable attributes.
 

docs/advanced_documentation/native-data-interface.md

@@ -170,7 +170,6 @@ and predefines all the corresponding `numpy.dtype`.
 The detailed explanation of all attributes of each component is given in
 [Graph Data model](../user_manual/data-model.md#attributes-of-components).
 
-
 One can import the `power_grid_meta_data` to get all the predefined `numpy.dtype` and create relevant arrays.
 The code below creates an array which is compatible with transformer input dataset.
 

docs/api_reference/python-api-reference.md

@@ -8,7 +8,7 @@ SPDX-License-Identifier: MPL-2.0
 
 This is the Python API reference for the `power-grid-model` library.
 Due to the nature of how Python module works, we cannnot hide the implementation detail completely from the user.
-As a general rule, any Python modules/functions/classes which are not documented in this API documentation, 
+As a general rule, any Python modules/functions/classes which are not documented in this API documentation,
 are internal implementations.
 **The user should not use any of them. We do not guarantee the stability or even the existence of those modules.**
 

docs/contribution/folder-structure.md

@@ -21,5 +21,5 @@ The repository folder structure is as follows. The `docs` and `scripts` folders
   - `benchmark_cpp` contains a benchmark test case generator in C++.
   - `package_tests` contains an integration test CMake project that tests whether the C API package is correctly installed.
   - `unit` folder contains tests for the python code.
-  - `data` contains validation test cases designed for every component and algorithm. Some sample network types are also included. 
+  - `data` contains validation test cases designed for every component and algorithm. Some sample network types are also included.
   The validation is either against popular power system analysis software or hand calculation.

docs/quickstart.md

@@ -57,7 +57,7 @@ node['u_rated'] = [10.5e3, 10.5e3]
 The code above generates a node input array with two nodes,
 and assigns the attributes of the nodes to the array.
 Similarly, we can create input arrays for line, load, and generation.
-A dictionary of such arrays is used for `input_data` and `update_data`. 
+A dictionary of such arrays is used for `input_data` and `update_data`.
 
 ```python
 # line
@@ -112,8 +112,8 @@ model = PowerGridModel(input_data, system_frequency=50.0)
 
 ## Power Flow Calculation
 
-To run calculations, use the object methods {py:class}`power_grid_model.PowerGridModel.calculate_power_flow` 
-or {py:class}`power_grid_model.PowerGridModel.calculate_state_estimation` functions. 
+To run calculations, use the object methods {py:class}`power_grid_model.PowerGridModel.calculate_power_flow`
+or {py:class}`power_grid_model.PowerGridModel.calculate_state_estimation` functions.
 Refer [Calculations](user_manual/calculations) for more details on the many optional arguments.
 
 ```python

docs/user_manual/calculations.md

@@ -652,7 +652,7 @@ We provide the control logic used for tap changing. For simplicity, we demonstra
   - Exploit the neighbourhood of all transformers (see {hoverxreftooltip}`user_manual/calculations:Initialization and exploitation of regulated transformers`)
     - Re-run the iteration in the above if any of the tap positions changed by the exploitation.
 
-In the case where the control side of the regulator and the tap side of the transformer are at the same side, the control logic of taps will be reverted (see `user_manual/calculations:Initialization and exploitation of regulated transformers`). 
+In the case where the control side of the regulator and the tap side of the transformer are at the same side, the control logic of taps will be reverted (see `user_manual/calculations:Initialization and exploitation of regulated transformers`).
 The exploitation of the neighbourhood ensures that the actual optimum is not accidentally missed due to feedback mechanisms in the grid.
 
 ```{note}
@@ -688,7 +688,6 @@ Internally, to achieve an optimal regulated tap position, the control algorithm
 | regulator control side != transformer tap side | `tap_max`       | `tap_min`       | step up      | step down  |
 | regulator control side == transformer tap side | `tap_min`       | `tap_max`       | step down    | step up    |
 
-
 ##### Search methods used for tap changing optimization
 
 Given the discrete nature of the finite tap ranges, we use the following search methods to find the next tap position along the exploitation direction.