Skip to content

Latest commit

 

History

History
90 lines (55 loc) · 5.36 KB

contributing.md

File metadata and controls

90 lines (55 loc) · 5.36 KB

Contribute to Astronomer docs

If you'd like to contribute to Astronomer docs directly, you are welcome to create a Pull Request (PR) to this repository with your suggested changes. To do so:

  1. Clone this repository
  2. Create a branch off of main
  3. Make your changes in that branch
  4. Submit a PR for review

Once you have submitted a PR for your changes, Netlify will add a comment to your PR that includes a link to a staging website with your changes.

Small edits and typo fixes don't need to be linked to an issue and should be merged quickly. To get a timely review on a larger contribution, we recommend first creating a GitHub issue describing the problem and linking that within your PR.

Every update to the main branch of this repository will trigger a rebuild of our production documentation page at https://www.docs.astronomer.io. It might take a few moments for your merged changes to appear.

For more detailed instructions and workflows when contributing to docs as an Astronomer team member, see the Astronomer Notion.

Docs Structure

There are 3 core documentation folders in this repository:

  • astro
  • software
  • learn

These folders contain the primary Astronomer docsets that you see by default on Astronomer's documentation site. Docs for the Astro CLI live within the astro folder.

The software directory is equivalent to the Latest version of the Astronomer Software docset, which is the docset that users see by default when accesssing docs.astronomer.io/software. An additional software_versioned_docs folder contains docsets for previous versions of Software. Whenever there's a new release of Astronomer Software, a new versioned docset is copied from software and added to this folder, with all links and sidebars updated automatically by Docusuaurs.

Screen Shot 2022-01-04 at 11 22 19 AM

If you're working on a change in Software docs, you should work primarily in software. Make changes to software_versioned_docs only if your change is version-specific or a critical fix (e.g. incorrect or out-of-date information).

Build Astronomer Docs Locally

If you want to submit a change to the Astronomer docs site itself, or test a screenshot, GIF, or a new documentation file, you may want to build and test your documentation change locally. Astronomer docs are built with Docusaurus, which is an open-source documentation framework and our static site generator. The Astronomer docs site is built on Netlify. Read the following sections for instructions on how to build and test your documentation changes locally with Docusaurus and Yarn.

Installation

To build docs locally, you need to install both Node and Yarn. While Yarn is included in Node, starting in 2020, the Yarn binaries are bundled within Corepack. If you're installing Node for the first time, you need to manually enable Corepacks before you can use Yarn.

  1. Follow the instructions on Nodejs to install Node, then confirm that you successfully installed Node by running the following command:

    node -version
  2. Run the following command to enable corepacks and make Yarn available:

    corepack enable

After you install Node and enable Yarn with Corepacks, Docusaurus commands are available when you open the docs directory from your terminal.

Please read the Docusaurus documentation for information on installing other tools you'll need to work with Docusaurus locally.

If you used an alternative package manager to install Node, such as npm or homebrew, you might need to troubleshoot your install.

Troubleshoot Yarn installations

  1. Run the following command to check your Node version:

    node --version
  2. Adjust your installation based on the output of the command:

    • Node and yarn are installed, but need to be updated: Use a package manager like npm or nvm to update your version, or download the installer from the Node.js site.
    • Node is installed, but you cannot enable Corepack: If you installed Node using a package manager, and it's above version 16.10, but Corepack isn't available, follow the instructions for installing Corepack with npm or installing Corepack with Homebrew or nvm, then run the following command to enable Corepack:
    corepack enable

Local Development

To serve a local version of the docs site with your changes, run:

yarn run start

You might also need to install fs-extra before you can build the site locally. To install it, run:

yarn add fs-extra

This command both builds and serves your local changes. By default, your local build is accessible at localhost:3000. From here, any changes you save in your text editor will render on this local site in real time.