How to Edit Docs
Learn the process of editing docs by adding some content to a test document.
Markdown, MkDocs, Mou
The Mynewt documentation you see on the Apache incubator website is a bunch of HTML files generated using MkDocs which is a simple static site generation tool geared towards building project documentation. You can read about it at http://www.mkdocs.org. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool (which in our case is MkDocs).
The HTML pages are generated periodically after changes have been reviewed and accepted into the master branch.
Access to the Apache repo
Get an account on Apache. You do not need a committer account to view the website or clone the repository but you need it to push changes to it.
If you are not a committer, you may follow the proposed non-committer workflow to share your work. The direct link to the proposed workflow is https://git-wip-us.apache.org/docs/workflow.html. You will find the steps described in more detail later in this tutorial.
Editing an existing page
- Create a fork on the github mirror.
- Create a new branch to work on your documentation and move to that branch.
$ git checkout -b <your-branch-name>
- Make changes directly on github.com. Generate a pull request. Alternatively, you can edit locally on your machine, push the branch (or the changes in the branch) to your fork on github.com, and then generate a pull request.
Adding a new page
If you create a new file somewhere in the
docs subdirectory to add a new page, you have to add a line in the
mkdocs.yml file at the correct level. For example, if you add a new module named "Wi-Fi" by creating a new file named
wifi.md in the
network directory, you have to insert the following line under
Networking User Guide in the
mkdocs.yml file (at the same level as the
docs directory). In this example, a link will show up in the navigation bar on the left under "Networking User Guide" titled "Wi-Fi" and take the user to the contents of the 'wifi.md' file when the link is clicked. Note: The change will show up on this Mynewt site only after your pull request is merged in and the updated site is generated.
- 'Wi-Fi': 'wifi.md'
Local preview of HTML files
You have the option to install MkDocs and do a local conversion yourself to preview the pages using the built-in webserver that comes with MkDocs. In order to install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have them already (usually you will).
$ python --version Python 2.7.2 $ pip --version pip 1.5.2 $ pip install mkdocs
You will then run the built-in webserver from the root of the documentation directory using the command
mkdocs serve. The root directory for documentation is
incubator-mynewt-site or the directory with the
$ ls docs images mkdocs.yml $ mkdocs serve
For more information on MkDocs go to http://www.mkdocs.org.