From 03f7a03ff4a52dde98ac6d766260fe5fca0cdd26 Mon Sep 17 00:00:00 2001 From: Mike Kasberg Date: Mon, 19 Feb 2024 09:40:02 -0700 Subject: [PATCH] Improve the README I recently contributed some docs improvements for the first time, and I ran a local preview before submitting my PR. I found the instructions in the README to be a little outdated and confusing, so I'd like to propose some changes that might make this easier for others: - A separate web server is not actually required. mkdocs includes a web server with `mkdocs serve`. - Installing mkdocs alone is not sufficient. `mkdocs-material` is required but this isn't mentioned in this section of the README. - The easiest way to run the site locally is probably to just use the one-liner docker command, as documented in the [mkdocs-material documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/). --- README.md | 47 +++++++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index b8b67e7fc..3bbf913db 100644 --- a/README.md +++ b/README.md @@ -12,21 +12,22 @@ If possible, it is preferable to store image content within this repository at ` ### How to add a new page -Let’s consider an example. Let’s imagine we want to add a page called `Top 5 mistakes` in section `Basics` after the `Getting Started` page. This page already exists, so you can already see the results in WLED Docs, but let’s imagine the page is not there and we will go steps needed to add it: +Let’s consider an example. Let’s imagine we want to add a page called `Top 5 mistakes` in section `Basics` after the `Getting Started` page. This page already exists, so you can already see the results in WLED Docs, but let’s imagine the page is not there and we will go over the steps needed to add it: -1) Create a file that should contain the documentation. As we want to place the new page in section `Basics` it makes sense to put this file in subfolder `docs/basics/`. In our example we call the file `top5_mistakes.md`. You can use another .md file as an example. Important is to have the following few lines at the beginning of the file: -``` ---- -title: TOP 5 mistakes -hide: - # - navigation - # - toc ---- -``` -Don’t forget to adapt the title. + 1. Create a file that should contain the documentation. As we want to place the new page in section `Basics` it makes sense to put this file in subfolder `docs/basics/`. In our example we call the file `top5_mistakes.md`. You can use another .md file as an example. Important is to have the following few lines at the beginning of the file: + ``` + --- + title: TOP 5 mistakes + hide: + # - navigation + # - toc + --- + ``` + Don’t forget to adapt the title. + + 2. Edit `mkdocs.yml` file. Take care that indentations play an important role in .yml files. Go to `nav:` section in this file and add a new line after the line `- Getting Started: basics/getting-started.md` as we want to add a new page after the `Getting Started` page. The new line must have the same indentation as the previous line and the content is `- Top 5 mistakes: basics/top5_mistakes.md`. By this we say that the new page must be called `Top 5 mistakes` and its content is in the file `top5_mistakes.md` we created before in subfolder `basics`. -2) Edit `mkdocs.yml` file. Take care that indentations play an important role in .yml files. Go to `nav:` section in this file and add a new line after the line `- Getting Started: basics/getting-started.md` as we want to add a new page after the `Getting Started` page. The new line must have the same indentation as the previous line and the content is `- Top 5 mistakes: basics/top5_mistakes.md`. By this we say that the new page must be called `Top 5 mistakes` and its content is in the file `top5_mistakes.md` we created before in subfolder `basics`. -That is! +That's it! ### How to add a new section @@ -34,10 +35,20 @@ It is even easier. Take a look at `nav:` section in `mkdoks.yml` file. To add a ### How to test the representation of the documentation in web locally (on Windows, MAC OS X or Linux) -You would need to install some tools: +The easiest way to preview the documentation locally is with Docker, but you can also do it by installing mkdocs-material with Python. We'll outline both options below. In either case, you'll need a local copy of this repository to work with (either via `git clone https://github.com/Aircoookie/WLED-Docs` or by downloading the sources). + +#### Run Locally with Docker + +You must have [Docker](https://www.docker.com/products/docker-desktop/) installed. From a terminal in the `WLED-Docs` folder, run: + +``` +docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material +``` + +The docker container builds and serves the site. You can see it at . Use Ctrl-C to stop the server. See the [mkdocs-material documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write) for more info. -1) WEB Server. The probably easiest way is to use [XAMPP](https://www.apachefriends.org/index.html) to run local WEB server on your PC/Laptop. After installing you would need to start XAMPP Control Panel and run Apache Server. In the folder where XAMPP is installed to you will find a subfolder called `htdocs`. This is the content of the WEB Server and you have to put WLED Docs web pages there, for example in subfolder called `wled-docs`. Later, after generating pages using mkdocs, you will be able to access them via `http://localhost/wled-docs/site/` -2) [Python](https://www.python.org/) -3) [MkDocs](https://www.mkdocs.org/user-guide/installation/#mkdocs-installation) +#### Run Locally with mkdocs -Now you can downlaod WLED Docs sources from the repository to subfolder `wled-docs` in the folder `htdocs` in your XAMPP installation (or if you have git installed you can use git command to clone like `git clone --branch main https://github.com/Aircoookie/WLED-Docs`). To "compile" the resulting web pages you have to run `mkdocs build` command in the `wled-docs` folder using command line. It generates subfolder 'site' with the resulting web pages and you can access them in your browser via `http://localhost/wled-docs/site/` +1. You must have [Python](https://www.python.org/) installed. +2. Building the docs requires [mkdocs-material](https://squidfunk.github.io/mkdocs-material/getting-started/). This can be installed with pip or [pipx](https://github.com/pypa/pipx). +3. From the `WLED-Docs` directory, run `mkdocs serve`. This will build the site and serve it. View the site at .