Skip to content

Submitting a Pull Request

To add or update content for a doc site, you need to make the changes locally and then submit a pull request for review.

Prerequisites

Make sure your device meets the system requirements

Set up your dev environment

Learn the basics about creating and building doc sites

Instructions

Here's how to make doc updates and submit a pull request.

  1. Open GitHub Desktop.

  2. Complete one of the following:

    • If you have worked on these docs before, fetch the latest version of the doc repo to your local device.
    • If you haven't worked on these docs before, clone the doc repo to your local device.

  3. Create a new branch off the develop branch.

  4. Open the docs repo in a source code editor.
  5. Open a command-line application.
  6. Browse to the local directory for the docs.

  7. Run the mkdocs serve command.

    Note

    If there is an issue running the docs locally, an error will display indicating the issue. More than likely you are missing a file or have used bad syntax somewhere and the message will tell you exactly where to look.

  8. Open a web browser and go to: http://127.0.0.1:8000/

    You should now see a preview of the docs in the browser.

    Tip

    As you make changes, the local version of the docs updates automatically.

  9. Update the docs.

    Tip

    See the Recommended Reading section for tips on how to write and lay out docs.

  10. Once you are finished making updates, open GitHub Desktop, commit your changes to your branch, and push the branch to GitHub.

  11. Open a web browser and access the doc repo in GitHub.

  12. Submit a pull request and request a review of your changes from Andy Graham.

    Andy will then review your changes and approve once acceptable. The updates you made will then get deployed to the live docs site.

Tips

  • Take a look at the repos for existing docs, such as the DataSeer docs repo, to see examples of how to build and layout content.

  • It is highly recommended that you run the docs locally when you are making updates. This lets you see a live preview of changes once you save them and also lets you see details about errors and bad markdown syntax.

    • To run the docs locally, open a command-line tool, browse to the local directory for the docs, and run the mkdocs serve command.
    • Open a web browser and go to: http://127.0.0.1:8000/ to see a live preview of the updated docs.
    • Keep an eye on the command-line for notifications about errors and bad markdown syntax.

  • When you add a new page to a doc site, make sure you also add a link to it under nav in the mkdocs.yml file. This ensures that users can access the page from the left navigation bar.

  • Store images for docs in the /docs/assets/images folder. This makes it easier to locate images and allows you to re-use images in multiple articles.

You must write docs in GitHub Flavored Markdown (GFM). However, the theme for the docs features a number of extensions that give you the ability to add elements using custom markdown syntax.

Check out the following resources to learn more:

Resource Description
Markdown Cheatsheet Learn the basics about writing in markdown.
MkDocs-Material: Extensions Learn the special markdown syntax you can use to add callouts and code blocks.
MkDocs User Guide Learn how to write and layout markdown files.

Next Step

Review the pull request

Last update: June 26, 2020