Merge pull request #336 from Boavizta/335-broken-link-or-missing-page…

…-in-api-documentation

Document how to work on the docs and how to verify links

docs/README.md

@@ -11,27 +11,46 @@ Content:
 5. Getting started: some basic API queries explained.
 6. How to guides - for developers who want to use the API
 
-## Install & launch a local documentation server
+## Work on the documentation
+
+### Install the documentation tools
 
 Documentation is generated from markdown using `mkdocs` with the `material` theme.
 
 ```bash
-# install mkdocs and its extensions
+# (preferred) Install mkdocs and its extensions
+poetry install --with docs
+
+# (old way) install mkdocs and its extensions
 pip install mkdocs mkdocs-render-swagger-plugin mkdocs-material mkdocs-macros-plugin
 ```
 
 💡 Do not mixup _pip_ and _brew_ installation of `mkdocs` (see [troubleshooting](https://jimandreas.github.io/mkdocs-material/troubleshooting/)).
 
+### Launch a local documentation server
+
 ```bash
+# If mkdocs is installed via poetry (preferred)
+# from the root of the cloned repository
+cd docs
+poetry run mkdocs serve
+```
+
+```bash
+# If mkdocs is installed globally
 # from the root of the cloned repository
 cd docs
 mkdocs serve
 ```
 
 Open <http://localhost:8080>
 
-## Access latest published documentation using docker
+### Verify the links
 
 ```bash
-docker run ghcr.io/boavizta/tools-doc:latest
+cd docs
+# Check the warnings in the output for broken links 
+poetry run mkdocs build
+# Test validity of external links 
+poetry run poetry run linkcheckMarkdown --recurse --verbose docs
 ```

docs/docs/Explanations/auto_complete.md

@@ -4,9 +4,9 @@ Any calculation using the API is made easier thanks to the **data auto-complete
 
 the API implements several approaches to complete the missing information:
 
-* ```COMPELETE``` : The API infer the value based on the user inputs (e.g. `manufacturer` and `family` for a CPU ```name```).  
+* ```COMPLETE``` : The API infer the value based on the user inputs (e.g. `manufacturer` and `family` for a CPU ```name```).  
 * ```DEFAULT``` : The API use a default value for those missing attributes (e.g. europe for the default ```usage_location```). The default values can be set in the [configuration file](../config.md).
-* ```ARCETYPE``` : The API can use a value taken from an [archetype](archetypes.md).
+* ```ARCHETYPE``` : The API can use a value taken from an [archetype](archetypes.md).
 * ```CHANGED```: The API can change the value of an attribute to make the computation possible. This happens when you provide a value that is close to the value of an attribute but not exactly the same. For example, if you provide a ```family``` that is not in the database but is close to a family in the database, the API will change the ```family``` to the closest name in the database.
 
 The documentation about how attributes are auto-completed is given on each asset's documentation page.