This is the site documentation for the Apache Mynewt project. It is built using MkDocs.
This repo previously contained all documentation relating to Apache Mynewt. The
project documentation now resides in the
Code specific documentation is found in various mynewt-* code specific repos.
Archived versions of the project documentation for releases 1.3.0 and earlier
are found under
Clone the repo:
git clone https://github.com/apache/mynewt-site cd mynewt-site
Optional: it's a very good idea to use a
virtualenv venv . venv/bin/activate
Install the requirements:
pip install -r requirements.txt
- Fork the repo.
- Work on the
- Preview your changes using MkDocs.
- visit http://localhost:8000
- Submit a pull request.
Deploying the latest docs
NOTE: These instructions assume that your workspace has all the mynewt repos cloned under the same parent directory.
First follow the steps at mynewt-documentation
Most steps for releasing docs happen at the mynewt-documentation repo. Follow the instructions there first.
Merge all changes and update
- Merge pull requests to
- Switch to the master branch.
git checkout master
- While in master, do
git pull --rebase origin masterto pull the latest merged changes.
Cut a new versioned documentation set (if appropriate)
NOTE: Skip these steps if you are just refreshing the current documentation or site.
- Create a new stanza in
mkdocs.ymlto reflect the new version.
- At present
- And that should probably not change.
- At present
- Add a new stanza in
custom-theme/choose_doc_version.htmlfor the new version.
- Add a link to
docs/documentation.mdfor the new version.
- Add a Disallow section to
extras/robots.txtfor the new version so that these documents do not appear in search results before the latest docs.
- Commit these changes.
- Visit http://localhost:8000
- This will leave you on the
- Commit & push the changes.
The runtime-bot github user does a build every ~15 minutes and opens a Pull Request against the asf-site branch if there are any changes. It is recommended that the runtime-bot PRs are used to deploy changes to the site instead of PRs from individual contributors. The runtime-bot PRs give us repeatable builds using known versions of the build tools.
Links to Documentation
For the deployed site a version prefix is added to the URL for each mkdocs page. When developing there is no version prefix. If you want to link from a site page to a documentation page you should prefix the URL with /DOCSLINK/ so that the user is taken to the correct location when browsing in production.