Merge pull request #155 from Billy99/billy99-mkdocs-instruct

docs: update README for mkdoc instructions

README.md

@@ -1,37 +1,41 @@
 # Documentation for Kepler-Doc
 
-Follow [sustainable-computing.io](https://sustainable-computing.io/) to see documentation
+Follow [sustainable-computing.io](https://sustainable-computing.io/) to see the Kepler
+documentation.
 
 ## Install MkDocs
 
-**Requirements:**
-
-- Python 3.8
+Make sure `Python 3.8` or greater is installed, then run:
 
 ```bash
 pip install -r requirements.txt
 ```
 
-## Rendering adopters
+## mkdocs Commands
 
-- uses gomplate 3.11.4, either install it or use tea.xyz:
+To build the documentation site, simply run:
 
-    ```sh
-    sh <(curl https://tea.xyz) +gomplate.ca^v3.11.4 sh
-    ```
+```sh
+mkdocs build
+```
 
-- template adopters via:
+To preview the documentation from a build on a local machine, start the mkdocs dev-server with
+the command below, then open up `http://127.0.0.1:8000/` in your browser, and you'll see the default
+home page being displayed:
 
-    ```sh
-    gomplate -d adopters=./data/adopters.yaml -f templates/adopters.md -o docs/project/adopters.md
-    ```
+```sh
+mkdocs serve
+```
 
-## Commands
+To preview the documentation from a build on a remote machine, start the mkdocs dev-server with
+the command below, then open up `http://<ServerIP>:8000/` in your browser, and you'll see the default
+home page being displayed.
+Make sure port `8000` (or different port of choice) is opened up on the machine running the command
+below on:
 
-- `mkdocs new [dir-name]` - Create a new project.
-- `mkdocs serve` - Start the live-reloading docs server.
-- `mkdocs build` - Build the documentation site.
-- `mkdocs -h` - Print help message and exit.
+```sh
+mkdocs serve -a 0.0.0.0:8000
+```
 
 ## Layout
 
@@ -60,3 +64,16 @@ GitHub codespaces [provides a generous free tier](https://github.com/features/co
 1. Make your changes as normal to the files within the `docs/` folder. The preview site will live reload
 1. When you're satisfied with your updates, commit them to your fork: `git add -A && git commit -sm "docs: a commit message here" && git push`
 1. Create a PR and you're done
+
+## Lint Checker
+
+When a Pull Request is pushed to `kepler-doc`, CI runs [Super-Linter](https://github.com/super-linter/super-linter).
+To run locally and verify there are no lint errors before pushing, run:
+
+```sh
+docker run -e RUN_LOCAL=true -e DEFAULT_BRANCH=main -e LINTER_RULES_PATH=/ -e VALIDATE_MARKDOWN=true -e VALIDATE_ALL_CODEBASE=true -v /path/to/kepler-doc:/tmp/lint --rm ghcr.io/super-linter/super-linter:v6.3.0
+```
+
+Replacing `/path/to/kepler-doc` with local path.
+This command checks all files via `-e VALIDATE_ALL_CODEBASE=true`.
+Upstream only checks modified files, but it is recommended to fix all lint errors.

docs/project/contributing.md

@@ -2,31 +2,80 @@
 
 We welcome all kinds of contributions to Kepler from the community!
 
-For an in-depth guide on how to get started, checkout the Contributing Guide [here](https://github.com/sustainable-computing-io/kepler/blob/main/CONTRIBUTING.md).
+For an in-depth guide on how to get started, checkout the Contributing Guide
+[here](https://github.com/sustainable-computing-io/kepler/blob/main/CONTRIBUTING.md).
 
-## Kepler adopters
+## Kepler Adopters
 
-You and your organisation are using Kepler? That's awesome. We would love to hear from you! 💚
+You and your organization are using Kepler? That's awesome. We would love to hear from you! 💚
 
-## Adding your organisation
+The yaml file in [here](https://github.com/sustainable-computing-io/kepler-doc/tree/main/data/adopters.yaml)
+contains a list of all Kepler adopters.
+If you want to add your organization to Kepler's list, just add an entry there and once merged you will be found under
+[Kepler Adopters](https://sustainable-computing.io/project/adopters/).
 
-The yaml file in [here](https://github.com/sustainable-computing-io/kepler-doc/tree/main/data/adopters.yaml) contains a list of all Kepler adopters.
+### Rendering Adopters
 
-If you want to add yourself just add an entry there and once merged you will be found under [adopters](https://sustainable-computing.io/project/adopters/).
+As part of adding an organization to the Kepler Adopters page, when
+[data/adopters.yaml](https://github.com/sustainable-computing-io/kepler-doc/blob/main/data/adopters.yaml)
+is updated, [gomplate](https://docs.gomplate.ca/) must be installed.
+The Kepler website uses it to render the Kepler Adopters page properly.
+
+!!! note
+    These steps are only needed if
+    [data/adopters.yaml](https://github.com/sustainable-computing-io/kepler-doc/blob/main/data/adopters.yaml)
+    is updated as part of adding an organization to the Kepler Adopters page.
+
+1. Install pkgx
+
+    ```sh
+    curl -Ssf https://pkgx.sh | sh
+    ```
+
+1. Install gomplate
+
+    ```sh
+    pkgx +gomplate.ca^v3.11.7
+    ```
+
+1. Enter the output from the previous command to update PATH. Example:
+
+    ```sh
+    PATH="$HOME/.pkgx/gomplate.ca/v3.11.7/bin${PATH:+:$PATH}"
+    ```
+
+1. Update adopters page using data from data/adopters.yaml
+
+    ```sh
+    gomplate -d adopters=./data/adopters.yaml -f templates/adopters.md -o docs/project/adopters.md
+    ```
+
+### Adding Your Organization
 
 To do so follow these steps:
 
 1. Fork the [kepler-doc](https://github.com/sustainable-computing-io/kepler-doc) repository.
-2. Clone it locally with `git clone https://github.com/<YOUR-GH-USERNAME>/kepler-doc.git`.
-3. (Optional) Add the logo of your organisation to docs/fig/logos. Good practice is for the logo to be called e.g. MY-ORG.png (=> docs/fig/logos/default.svg is the Kepler logo, it is used when no organisation logo is provided.)
-4. Add an entry to the YAML file with the name of your organisation, url that links to its website, and the path to the logo. Example:
+1. Clone it locally with `git clone https://github.com/<YOUR-GH-USERNAME>/kepler-doc.git`.
+1. (Optional) Add the logo of your organization to docs/fig/logos. Good practice is for the logo to be called e.g. MY-ORG.png (=> docs/fig/logos/default.svg is the Kepler logo, it is used when no organization logo is provided.)
+1. Add an entry to the YAML file with the name of your organization, url that links to its website, and the path to the logo. Example:
 
     ```yaml
         - name: Kepler
           url: https://sustainable-computing.io/
           logo: logos/kepler.svg
     ```
 
-5. Save the file, then do `git add -A` and commit using `git commit -s -m "Add MY-ORG to adopters"` (commit signoff is required, see [DCO of the kepler project](https://github.com/sustainable-computing-io/kepler/blob/main/DCO)).
-6. Push the commit with `git push origin main`.
-7. Open a Pull Request to [kepler-doc](https://github.com/sustainable-computing-io/kepler-doc)
+1. Verify the Kepler Adopters page updated properly by running the following commands (see
+   [Install MkDocs](https://github.com/sustainable-computing-io/kepler-doc?tab=readme-ov-file#install-mkdocs)
+   for more details on how to preview the documentation from a build):
+
+    ```sh
+    mkdocs build
+    mkdocs server
+    ```
+
+1. When happy with the changes, add the changed files using `git add -A` and then commit using
+   `git commit -s -m "Add MY-ORG to adopters"` (commit sign-off is required, see
+   [DCO of the kepler project](https://github.com/sustainable-computing-io/kepler/blob/main/DCO)).
+1. Push the commit with `git push origin main`.
+1. Open a Pull Request to [kepler-doc](https://github.com/sustainable-computing-io/kepler-doc)