docker run --rm -it -p 8001:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:5.1.0
In order to render and preview the site locally (without docker) you will need a few things to get started.
- You will need to install python and pip
- After python is installed, you'll need the following python dependencies:
pip install mkdocspip install mkdocs-material==5.1.0 - Once you have all the pre-reqs installed. You can simply run
mkdocs serveand view the rendered content locally and makes changes to your documentation and preview them in realtime with a browser open.
Publishing is done by the jenkins pipeline. Once a PR is merged, the changes will be reflected on the documentation site, hosted under gh-pages branch and served by Github Pages.
The different versions of the documentation are maintained in separate branches.
The main branch hosts the source files for the version that is under development as well as the following production site files:
docs/CNAME- DNS record which tells Github Pages to serve the content at https://docs.edgexfoundry.org instead of https://edgexfoundry.github.io/edgex-docsdocs/index.html- site index page that redirects from/to/{latest-release}docs/versions.json- version info to populate the site version drop-down menu
The pipeline copies the files to separate directories inside gh-pages branch. For example, when the dev version is 2.2:
| Source | Production |
|---|---|
| main/docs/CNAME | gh-pages/CNAME |
| main/docs/index.html | gh-pages/index.html |
| main/docs/versions.json | gh-pages/versions.json |
| main/docs_src/* | gh-pages/2.2/* |
| jakarta/docs_src/* | gh-pages/2.1/* |
| ireland/docs_src/* | gh-pages/2.0/* |
Other files such as for CI checks and guidelines are also copied from all branches.
When a new version of EdgeX is released, we version the docs as well. There are four steps to make this happen:
-
Create a branch without production site files
i) Create a branch from
mainfor the released documentation The branch name should be the new EdgeX release name. For example, for 2.2, akamakurabranch is created.ii) Remove production site files from the branch, listed here. This is necessary to avoid overriding production files; see #680.
-
Add the version to be added to the
docs/versions.jsonfile. This file will populate the drop down in the site deployed at https://docs.edgexfoundry.org
[
{"version": "1.1", "title": "1.1-Fuji", "aliases": []},
{"version": "1.2", "title": "1.2-Geneva", "aliases": []}
{"version": "[new version number here]", "title": "[name that is visible in the drop down]", "aliases": []}
]- The value placed in
versionproperty in the json above MUST match the name of the folder that contains the versioned content in the gh-pages branch. This is specified by updating thesite_dir:property in themkdocs.ymlfile:
site_name: EdgeX Foundry Documentation
docs_dir: ./docs_src
site_dir: ./docs/1.2 #UPDATE THE VERSION NUMBER HERE TO MATCH WHATS IN THE VERSION.JSON
site_description: 'Documentation for use of EdgeX Foundry'
site_author: 'Michael Johanson'
site_url: 'https://edgexfoundry.github.io/edgex-docs/'
repo_url: 'https://github.com/edgexfoundry/edgex-go'
repo_name: 'edgex/edgex-go'
copyright: 'Copyright © 2020 EdgeX Foundry'
...Once this is done and merged, the build job will place content in the specified folder in the gh-pages branch.
- Update the
docs/index.htmlto redirect from/to the most recent release directory. For example, if the latest release is2.1:
<!DOCTYPE html>
<html>
<head>
<title>Redirecting</title>
<script>
window.location.replace("2.1"); //UPDATE ME
</script>
</head>
<body>
</body>
</html>