Merge pull request #416 from davidzuhn/fix/link-moved

fix link to ble_gatt.h (nimble moved to separate repository)
tree: 158e727b460dcfd58036d824a87847ed1b01dcb3
  1. custom-theme/
  2. docs/
  3. extras/
  4. versions/
  5. .editorconfig
  6. .gitignore
  7. .mdlrc
  8. build.py
  9. deploy.sh
  10. mkdocs.yml
  11. README.md
  12. requirements.txt
  13. serve.py
README.md

The Apache MyNewt site is built using MkDocs.

Setup

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:

virtualenv venv
. venv/bin/activate

Install the requirements:

pip install -r requirements.txt

Submitting updates

  1. Fork the repo.
  2. Work on the master branch.
  3. Preview your changes using MkDocs.
  4. Submit a pull request.

Releasing a versioned set of MyNewt documentation

When a release of MyNewt OS and its associated tools occurs, a new version directory should be created to hold all docs pertaining to that release. The documentation in the git master branch of this repository always shows the latest docs under development. The following steps will create a documentation directory for a new release and make it available from the mynewt-site.

Merge all changes and update

  1. Merge pull requests to master on github.
  2. Switch to the master branch.
    • git checkout master
  3. While in master, do git pull --rebase origin master to pull the latest merged changes.

Cut the new release documentation set

NOTE: Skip these steps if you are just refreshing the current documentation or site.

  1. Create a new stanza in mkdocs.yml to reflect the new version.
    • At present master is the latest version.
    • And that should probably not change.
  2. Add a new stanza in “custom-theme/choose_doc_version.html” for the new version.
  3. Create a new directory in the versions directory for this new version.
    • Copy the latest docs directory and mkdocs.yml file into the new version directory
    • Set extra.version to the new version in the copied mkdocs.yml file
    • Create a symbolic link to the customer-theme
  4. Commit these changes.

Build

  1. Run: ./build.py

Test

  1. Run: ./serve.py
  2. Visit http://localhost:8000

Deploy

  1. Run: ./deploy.sh build
  2. This will leave you on the asf-site branch.
  3. 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.

Link Checking

  1. Grab a link checking tool like Integrity
  2. Run: ./build.py --test-build
  3. Run: ./serve.py
  4. Point the link checker at http://localhost:8000/