Contribute to Nebari's documentation
A complete and accessible set of documentation is essential for an open source project's success. Thank you for making Nebari's documentation better!
Nebari has the following (broad) types of documentation:
- Narrative documentation in the form of tutorials, how-to's, and more, hosted on
nebari.dev
(this website). Keep reading this page to learn how you can contribute! - Docstrings and READMEs that are a part of the nebari codebase and other GitHub repositories in the nebari-dev, respectively. To contribute to these, check out Contribute to Nebari's codebase.
- Demos and examples for community self-study and conference presentations hosted at nebari/nebari-demo. To contribute examples, start at the Nebari Demo README.
Documentation style guide
We follow some style guidelines across the Nebari documentation resources to maintain consistency and keep our documentation accessible to everyone. Take a few minutes to go through the key principles before contributing. We encourage you to read the complete style guide when you get a chance. Many suggestions in the style guide are good practices to follow in day-to-day written communication as well.
Read the Nebari documentation style guide →
Documentation tools
Nebari's documentation is built with Docusaurus 2, a modern static website generator. With Docusaurs, you can author documentation using a friendly Markdown format, which are converted to consistent documentation page. If you are not familiar with Markdown, check out the Markdown Guide project for a comprehensive reference.
In addition to general Markdown, Docusaurs has some helpful special features like tabs and admonitions, go through the Markdown Features section of the Docusaurus documentation to learn about them!
We use Netlify for deploying the documentation. The deployment to nebari.dev
is automatically handled by Netlify when your content is merged into the nebari-docs/main
branch.
Netlify will also add a nifty preview link to any PR as a comment. This way you can make sure everything is working as expected.
Documentation framework
Nebari uses the Diátaxis framework for technical documentation. The Diátaxis framework recognizes four types of documentation: Tutorials, how-to guides, explanations (called "conceptual guides" in Nebari), and references. As described in the following diagram, each of these types of documentation serve a different purpose, and therefore, are written differently:
Set up your local repository
Make a fork of the
Nebari-docs
repository to your GitHub account.Clone the forked repository to your local machine:
git clone https://github.com/<your-username>/nebari-docs.git
Set up your local development environment
Optional: Create an isolated environment
To create an environment with
conda
:conda create -n nebari-docs python=3.9
note
You need Python >= 3.7 to complete the setup and install the
pre-commit
package manager later.Activate the environment:
conda activate nebari-docs
Prerequisites: Node.js
To build the site you will need to have Node.js installed. To see if you already have Node.js installed, type the following command into your local command line terminal:
node -v
# v18.10.0
If you see a version number, such as v18.10.0
printed, you have Node.js installed, you can move to the next section!
If you get a command not found
error (or similar phrasing), install Node.js before continuing.
To install node visit nodejs.org or check any of these tutorials for Ubuntu, Debian, or macOS.
If you created an environment with conda
, you can install Node.js with:
conda install -c conda-forge nodejs
Prerequisites: Yarn
Once you have Node.js installed you can proceed to install Yarn. Yarn has a unique way of installing and running itself in your JavaScript projects. First, you install the yarn command globally, then you use the global yarn command to install a specific local version of Yarn into your project directory.
The Yarn maintainers recommend installing Yarn globally by using the NPM
package manager,
which is included by default with all Node.js installations.
Use the -g
flag with npm
install to do this:
npm install -g yarn
After the package installs, have the yarn
command print its own version number to verify if it was installed properly:
yarn --version
# 1.22.11
Install documentation dependencies
Move to the
/docs
directory:cd docs
Install the necessary dependencies:
yarn install
Pre-commit hooks
Similar to the Nebari codebase, the nebari-docs
repository uses a number of pre-commit hooks to standardize our YAML and Markdown structure.
Navigate to the root of this project. If you're in the
docs
subdirectory, you can run "cd ..
" to go back to the root.Follow the instructions in the Pre-commit hooks section of Contribute to Nebari's codebase to install the pre-commit hooks.
Develop and submit your contribution
Once you have the dependencies and the pre-commit hooks installed, you can start writing and updating the documentation.
The workflow to develop your contribution is similar to contributing code. The difference is that you're writing or updating Markdown files. Go through the following sections to learn about creating branches, making pull requests, and how the contribution review process works:
Start a live version of the documentation
To see a live local version of the docs while editing, run the following command from the docs
subdirectory:
yarn start
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
note
By default, this will load your site at http://localhost:3000/.
You can specify a different port with yarn start --port <port-number>
.
(Optional) Build the site locally
You can build the static files of the documentation to see how they would look once deployed to nebari.dev
:
yarn build
This command generates static content into the docs/build
directory and can be served using any static contents hosting service.
You can check the newly built site with the following command:
yarn run serve
note
By default, this will also load your site at http://localhost:3000/.
You can specify a different port with yarn start --port <port-number>
.
Linting and formatting
In addition to the pre-commit
hooks, you can run the Docusaurus linter (ESLint) and formatter (Prettier) to ensure code consistency before submitting a PR.
Navigate to the
docs
directory.Run the following commands:
yarn run lint
yarn run format
Adding a new dependency
If you need to a new dependency to the project, use the add
sub-command:
yarn add package-name