The most common use case for local development of edgex-docs will be to verify changes to the HTML. To facilitate docs verification you can run the following command:
make serveOnce running, you can view the rendered content locally and makes changes to your documentation and preview them in realtime with a browser at:
http://localhost:8008
If you only want to verify the documentation will build successfully you can run the following command:
make buildWhen done, you can clean up with:
make cleanIn 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 mkdocs
pip install mkdocs-material==8.2.1
- 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 at http://0.0.0.0:8001/edgex-docs.
To check that all the links in the documentation set are valid:
-
Install the htmlproofer plugin (native only):
Note: if using the docker method, this is already installed in the image
pip install mkdocs-htmlproofer-plugin
-
Export the
ENABLED_HTMLPROOFERenvironment variable.Note: This adds about 5 minutes each time a change is made, so it is recommended to do once all changes are ready.
export ENABLED_HTMLPROOFER=true -
Run
make buildormake serve. Broken links will be listed at the end of the build process.
Warning: the check for invalid / broken links does take some time and will add significantly to the build and serve times.
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>
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
