Merge pull request #146 from alliander-opensource/feature/doc-os-move

OS docs move and fix links

Author: TonyXiang8787

.gitignore

@@ -506,3 +506,7 @@ cpp_coverage.xml
 
 # generated version file
 PYPI_VERSION
+
+# docs builds
+docs/make.bat
+docs/Makefile

README.md

@@ -60,8 +60,8 @@ SPDX-License-Identifier headers are used to show which license is applicable.
 The concerning license files can be found in the [LICENSES](LICENSES) directory.
 
 # Contributing
-Please read [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) and [CONTRIBUTING](CONTRIBUTING.md) for details on the process 
+Please read [CODE_OF_CONDUCT](docs/CODE_OF_CONDUCT.md), [CONTRIBUTING](docs/CONTRIBUTING.md), [PROJECT GOVERNANCE](docs/PROJECT_GOVERNANCE.md) and [RELEASE](docs/release_and_support/RELEASE.md) for details on the process 
 for submitting pull requests to us.
 
 # Contact
-Please read [SUPPORT](SUPPORT.md) for how to connect and get into contact with the Power Gird Model project.
+Please read [SUPPORT](docs/release_and_support/SUPPORT.md) for how to connect and get into contact with the Power Gird Model project.

CODE_OF_CONDUCT.md renamed to docs/CODE_OF_CONDUCT.md

@@ -69,4 +69,4 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai
 
 This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
 available at
-https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+[](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html)

CONTRIBUTING.md renamed to docs/CONTRIBUTING.md

@@ -27,10 +27,10 @@ We recognize different levels of contributions as shown below in increasing orde
 
 The repository folder structure is as follows. The `examples`, `docs` and `scripts` folders are self-explanatory.
 
-- The C++ calculation core is inside [include/power-grid-model](include/power-grid-model).
-- The python interface code is in [src/power_grid_model](src/power_grid_model)
-- The code for validation of input data is in [validation](src/power_grid_model/validation) folder.
-- The [tests](tests) folder is divided in the following way:
+- The C++ calculation core is inside {{ "[include/power-grid-model]({}/include/power-grid-model)".format(gh_link_head_tree) }}.
+- The python interface code is in {{ "[src/power_grid_model]({}/src/power_grid_model)".format(gh_link_head_tree) }}
+- The code for validation of input data is in {{ "[validation]({}/src/power_grid_model/validation)".format(gh_link_head_tree) }} folder.
+- The [tests]({{ gh_link_head}}tests) folder is divided in the following way:
   - `cpp_unit_tests` contains the tests for the C++ calculation core.
   - `benchmark_cpp` contains a benchmark test case generator in C++.
   - `unit` folder contains tests for the python code.
@@ -77,7 +77,7 @@ Tip: Use [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to format
 This project uses [pre-commit](https://pre-commit.com/) to run a list of checks (and perform some automatic
 corrections) to your code (style) before each commit. It is up to the developer to choose whether you would like to 
 use this tool or not. The goal is to make sure that each commit will pass the quality checks in the github actions
-workflow. Currently, these hooks are defined in [`.pre-commit-config.yaml`](.pre-commit-config.yaml):
+workflow. Currently, these hooks are defined in {{ "[`.pre-commit-config.yaml`]({}/.pre-commit-config.yaml)".format(gh_link_head_blob) }}:
 * **reuse**: check if all licence headers and files are in place
 * **isort**: group and sort import statements 
 * **black**: check and correct code style in a very strict manner

PROJECT_GOVERNANCE.md renamed to docs/PROJECT_GOVERNANCE.md

@@ -174,7 +174,7 @@ pytest
 ### Build CMake Project
 
 There is a convenient shell script to build the cmake project:
-[`build.sh`](../build.sh). You can study the file and write your own build script. Four configurations are pre-defined
+{{ "[`build.sh`]({}/build.sh)".format(gh_link_head_blob) }}. You can study the file and write your own build script. Four configurations are pre-defined
 for two input arguments, which will be passed into `cmake`. It includes debug or release build, as well as the option to
 build test coverage or not.
 

docs/advanced_documentation/build-guide.md

@@ -11,6 +11,23 @@
 copyright = "2022, alliander-opensource"
 author = "alliander-opensource"
 
+# -- Setup
+
+import os
+
+# Fix linking in github and rtd
+link_head_gh = "https://github.com/alliander-opensource/power-grid-model/"
+if "READTHEDOCS" in os.environ:
+    import git
+
+    commit_version = git.Repo(search_parent_directories=True).head.object.hexsha
+    link_head_gh_blob = link_head_gh + "blob/" + commit_version
+    link_head_gh_tree = link_head_gh + "tree/" + commit_version
+else:
+    link_head_gh_blob = ""
+    link_head_gh_tree = ""
+
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -37,9 +54,22 @@
     "*/.ipynb_checkpoints/*",
 ]
 
-# -- myst parser config ------------------------------------------------------
+# -- myst parser and myst_nb config ------------------------------------------------------
 # label references for depth of headers: label name in anchor slug structure
 myst_heading_anchors = 3
+# execute jupter notebooks output before building webpage
+jupyter_execute_notebooks = "off"
+# Extentions in myst
+myst_enable_extensions = [
+    "dollarmath",
+    "substitution",
+]
+# Global substitutions
+myst_substitutions = {
+    "gh_link_head_blob": link_head_gh_blob,
+    "gh_link_head_tree": link_head_gh_tree,
+}
+
 
 # -- hoverxref config --------------------------------------------------------
 # hover tooltip on python classes
@@ -69,7 +99,3 @@
 
 # -- sphinx.autosectionlabel config -------------------------------------------
 autosectionlabel_prefix_document = True
-
-# -- myst_parser or myst_nb -------------------------------------------------
-# markdown links [](relative_path\file.ext#section-in-slug)
-myst_heading_anchors = 3