Code Monkey home page Code Monkey logo

edgex-docs's Introduction

Documentation for developing with EdgeX-Docs

Build Status GitHub Pull Requests GitHub Contributors GitHub Committers GitHub Commit Activity

Local Development (docker) (recommended)

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 serve

Once running, you can 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


If you only want to verify the documentation will build successfully you can run the following command:

make build

When done, you can clean up with:

make clean

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==8.2.1

  1. 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 at http://0.0.0.0:8001/edgex-docs.

Checking for broken links when developing docs

To check that all the links in the documentation set are valid:

  1. Install the htmlproofer plugin (native only):

    Note: if using the docker method, this is already installed in the image

    pip install mkdocs-htmlproofer-plugin
  2. Export the ENABLED_HTMLPROOFER environment 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
  3. Run make build or make 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" your changes

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:

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.

Versioning the docs

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

  1. Create a branch without production site files

    i) Create a branch from main for the released documentation The branch name should be the new EdgeX release name. For example, for 2.2, a kamakura branch is created.

    ii) Remove production site files from the branch, listed here. This is necessary to avoid overriding production files; see #680.

  2. Add the version to be added to the docs/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. Update the docs/index.html to redirect from / to the most recent release directory. For example, if the latest release is 2.1:
<!DOCTYPE html>
<html>
<head>
<title>Redirecting</title>
<script>
    window.location.replace("2.1"); //UPDATE ME
</script>
</head>
<body>
</body>
</html>

edgex-docs's People

Contributors

akramtexas avatar alexcuse avatar beaufrusetta avatar bill-mahoney avatar bnevis-i avatar brian-intel avatar cherrycl avatar cjoyv avatar cloudxxx8 avatar edgex-jenkins avatar ejlee3 avatar ernestojeda avatar farshidtz avatar felixting avatar iain-anderson avatar jamesrgregg avatar jim-wang-intel avatar jinfahua avatar jinlinguan avatar jpwhitemn avatar lenny-goodell avatar mhall119 avatar michaelestrin avatar monicaisher avatar rsdmike avatar tombrennan-eaton avatar tonyespy avatar tsconn23 avatar vli11 avatar weichou1229 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.