/edgex-docs

Primary LanguagePython

Documentation for developing with EdgeX-Docs

Local Development (docker) (recommended):

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:5.1.0

Local Development (native)

In order to render and preview the site locally (without docker) you will need a few things to get started.

  1. You will need to install python and pip
  2. After python is installed, you'll need the following python dependencies: pip install mkdocs pip install mkdocs-material==5.1.0
  3. Once you have all the pre-reqs installed. You can simply run mkdocs serve and view the rendered content locally and makes changes to your documentation and preview them in realtime with a browser open.

"Publishing" your changes

Publishing is now done by the jenkins pipeline. Once a PR is merged to master, the changes will be reflected on the documentation site.

Versioning the docs

When a new version of EdgeX is released, we version the docs as well. There are three steps to make this happen:

  1. Add the version to be added to the versions.json file. 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": []}
]
  1. The value placed in version property 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 the site_dir: property in the mkdocs.yml file:
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.

  1. The last step, once everything is in place, is to update the site. The docs site is a statically hosted site on github pages from the gh-pages branch. Normally we leave this branch alone as the build job will take care of updating it. However, versioning is a bit different.You'll need to do TWO things. Ideally this would be automated, but it is manual for now given it happens once per release.
    1. You'll need to repeat step 1 against the gh-pages branch. Think of it as master is dev and gh-pages is prod.
    2. You'll need to update the index.html to redirect users to the current version:
<!DOCTYPE html>
<html>
<head>
<title>Redirecting</title>
<script>
    window.location.replace("1.2"); //UPDATE ME
</script>
</head>
<body>
</body>
</html>