diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index cc83d15965b..66483c43ea3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -26,6 +26,17 @@ repos: hooks: - id: check-hooks-apply - id: check-useless-excludes + - repo: https://github.com/thlorenz/doctoc.git + rev: v2.2.0 + hooks: + - id: doctoc + name: Add TOC for Markdown and RST files + files: + ^CONTRIBUTING\.md$|^README\.md$|^UPDATING.*\.md$|^chart/UPDATING.*\.md$|^dev/.*\.md$|^dev/.*\.rst$ + exclude: ^.*/.*_vendor/ + args: + - "--maxlevel" + - "2" - repo: https://github.com/Lucas-C/pre-commit-hooks rev: v1.3.1 hooks: diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md index d31005b477b..68544c3c45e 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTE.md @@ -57,7 +57,7 @@ Contributor Guide # Working with the project -Work with the site and documentation requires that your computer be properly prepared. Most tasks can +You should work with the site and documentation that requires that your computer be properly prepared. Most tasks can be done by the site.sh script ### Prerequisite Tasks @@ -69,7 +69,7 @@ The following applications must be installed to use the project: * Node 16 * Hugo -It is also worth adding SSH keys for the `github.com` server to trusted ones. It is necessary to clone repositories. You can do this using following command: +It is also worth adding SSH keys for the `github.com` server to trusted ones. It is necessary to clone repositories. You can do this using the following command: ```bash ssh-keyscan -t rsa -H github.com >> ~/.ssh/known_hosts ``` @@ -87,7 +87,7 @@ curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh sudo usermod -aG docker $USER ``` -Git must have commit author information configured, run these commands +Git must have to commit author information configured, run these commands ```bash git config --global user.email '' git config --global user.name '' @@ -112,7 +112,7 @@ To install git on macOS, install the XCode Command Line Tools with the following xcode-select --install ``` -Then, install [Homebrew](https://brew.sh). Once that has completed, you can install Hugo: +Then, install [Homebrew](https://brew.sh). Once that has been completed, you can install Hugo: ```bash brew install hugo ``` @@ -126,13 +126,13 @@ nvm use 16 ### Static checks -The project uses many static checks using fantastic [pre-commit](https://pre-commit.com/). Every change is checked on CI and if it does not pass the tests it cannot be accepted. If you want to check locally then you should install Python3.6 or newer together with pip and run following command to install pre-commit: +The project uses many static checks using fantastic [pre-commit](https://pre-commit.com/). Every change is checked on CI and if it does not pass the tests it cannot be accepted. If you want to check locally then you should install Python3.6 or newer together with pip and run the following command to install pre-commit: ```bash pip install -r requirements.txt ``` -To turn on pre-commit checks for commit operations in git, enter: +To turn on pre-commit checks for commit operations in Git, enter: ```bash pre-commit install ``` @@ -151,7 +151,7 @@ Pre-commit check results are also attached to your PR through integration with T ### Clone repository -To clone repository from github.com to local disk, run following command +To clone the repository from github.com to the local disk, run the following command ```bash git clone git@github.com:apache/airflow-site.git @@ -166,7 +166,7 @@ In order to manage your local environment for the project, use the `site.sh` scr build-site Prepare dist directory with landing pages and documentation preview-landing-pages Starts the web server with preview of the website - build-landing-pages Builds a landing pages + build-landing-pages Builds landing pages prepare-theme Prepares and copies files needed for the proper functioning of the sphinx theme. install-node-deps Download all the Node dependencies check-site-links Checks if the links are correct in the website @@ -174,23 +174,23 @@ In order to manage your local environment for the project, use the `site.sh` scr lint-js Lint Javascript files help Display usage -### How to add a new blogpost +### Adding a new blog post -To add a new blogpost with pre-filled frontmatter, in `/landing-pages/site` run: +To add a new blog post with pre-filled frontmatter, in `/landing-pages/site` run: ```bash hugo new blog/my-new-blogpost.md ``` That will create a markdown file `/landing-pages/site/content//blog/my-new-blogpost.md` -with following content: +with the following content: ``` --- title: "My New Blogpost" linkTitle: "My New Blogpost" author: "Your Name" -twitter: "Your Twitter ID (optional, remove if not needed)" -github: "Your Github ID (optional, remove if not needed)" -linkedin: "Your LinkedIn ID (optional, remove if not needed)" +Twitter: "Your Twitter ID (optional, remove if not needed)" +GitHub: "Your Github ID (optional, remove if not needed)" +LinkedIn: "Your LinkedIn ID (optional, remove if not needed)" description: "Description" tags: [] date: "2019-11-19" @@ -199,22 +199,22 @@ draft: true ``` Below frontmatter, put your blogpost content. -When you finish your writing blogpost, remember to **remove `draft: true`** from frontmatter. +When you finish your writing blog post, remember to **remove `draft: true`** from frontmatter. --- -To add a new blogpost manually, create a markdown file in `/landing-pages/site/content//blog/.md`. -The filename will also serve as URL for your blogpost. +To add a new blog post manually, create a markdown file in `/landing-pages/site/content//blog/.md`. +The filename will also serve as a URL for your blog post. -Then, **at the top of the file**, add frontmatter in following format: +Then, **at the top of the file**, add frontmatter in the following format: ``` --- title: "" linkTitle: "" author: "" -twitter: "" -github: "" -linkedin: "" +Twitter: "" +GitHub: "" +LinkedIn: "" description: "" tags: ["", "", ...] date: @@ -222,9 +222,9 @@ date: ``` Below frontmatter, put your blogpost content. -### How to add a blog post with images +### Adding a blog post with images -In order to add a new blog post with images, you need to add it in sub-folder of the "blog" folder and +In order to add a new blog post with images, you need to add it in the sub-folder of the "blog" folder and name your markdown file "index.md". Images placed in this folder can be referred to directly from the markdown file using this directive: @@ -232,7 +232,7 @@ the markdown file using this directive: ![Alt text](image.png) ``` -### How to add a new case study +### Adding a new case study To add a new case study with pre-filled frontmatter, in `/landing-pages/site` run: ```bash @@ -240,7 +240,7 @@ hugo new use-cases/my-use-case.md ``` That will create a markdown file `/landing-pages/site/content//use-cases/my-use-case.md` -with following content: +with the following content: ``` --- title: "My Use Case" @@ -261,14 +261,14 @@ text ##### What are the results? text ``` -When you finish your writing blogpost, remember to **remove `draft: true`** from frontmatter. +When you finish your writing blog post, remember to **remove `draft: true`** from frontmatter. --- To add a new case study manually, create a markdown file in `/landing-pages/site/content//use-cases/.md`. The filename will also serve as URL for the case study. -Then, **at the top of the file**, add frontmatter in following format: +Then, **at the top of the file**, add frontmatter in the following format: ``` --- @@ -280,7 +280,7 @@ quote: logo: "" --- ``` -Below frontmatter, put your blogpost content in following format: +Below frontmatter, put your blog post content in the following format: ``` #### What was the problem? @@ -324,7 +324,7 @@ logo: "my-case-study.svg" ``` -### How to add a new integration +### Adding a new integration In order to add a new integration, add an entry in `/landing-pages/site/static/integrations.json` file, following the format: @@ -339,13 +339,13 @@ following the format: Integrations are displayed in random order, which might be different on each site reload. To search for your integration, use the search functionality. -Providing an integration logo is **optional**. However, please take note that integrations with logo are be promoted +Providing an integration logo is **optional**. However, please take note that integrations with logo are being promoted by being displayed before integrations without a logo. -### How to add a new meetup +### Adding a new meetup In order to add an upcoming meetup, find your group in `/landing-pages/site/static/meetups.json` file -and put the meetup's date in following format: +and put the meetup's date in the following format: `MON, JAN 01, 6:00 PM` @@ -368,13 +368,13 @@ If your meetup group isn't on the list, add it following the format of existing ``` -# How to release new documentation +# Releasing new documentation -Building documentation for the Apache Airlfow project also requires Python3.6 with pip and graphviz. You also need to have additional `apache/airflow` repository available. +Building documentation for the Apache Airlfow project also requires Python3.6 with pip and graphviz. You also need to have an additional `apache/airflow` repository available. ### Prerequisite Tasks -You should install and set up all software from "Working with the project/Prerequisite tasks" section. +You should install and set up all software from the "Working with the project/Prerequisite tasks" section. The following additional application must be installed to use the project: @@ -384,12 +384,12 @@ The following additional application must be installed to use the project: **Debian installation:** -To install graphviz, pip for Debian, run following commands: +To install graphviz, pip for Debian, run the following commands: ```bash sudo apt install graphviz python3-pip -y ``` -You should also add `$HOME/.local/bin` to `$PATH`, run following command: +You should also add `$HOME/.local/bin` to `$PATH`, and run the following command: ```bash export PATH=$HOME/.local/bin:$PATH; ``` @@ -397,7 +397,7 @@ export PATH=$HOME/.local/bin:$PATH; ### Clone repositories -It is necessary to configure 2 variables that point to directories with repositories and one that describe current Airflow version. The next steps will assume that these variables are available. +It is necessary to configure 2 variables that point to directories with repositories and one that describes the current Airflow version. The next steps will assume that these variables are available. ```bash AIRFLOW_REPO=$HOME/airflow AIRFLOW_SITE_REPO=$HOME/airflow-site @@ -415,13 +415,13 @@ cd "${AIRFLOW_SITE_REPO}" && git submodule update --init --recursive To release a new documentation, follow these steps: -1. To prepare and install Sphinx theme, run following commands: +1. To prepare and install Sphinx theme, run the following commands: ```bash cd "${AIRFLOW_SITE_REPO}" && bash site.sh build-site cd "${AIRFLOW_SITE_REPO}" && bash site.sh prepare-theme cd "${AIRFLOW_SITE_REPO}/sphinx_airflow_theme" && pip3 install -e . ``` -2. To build documentation, run following commands: +2. To build documentation, run the following commands: ```bash cd "${AIRFLOW_REPO}" && git checkout "${AIRFLOW_VERSION}" cd "${AIRFLOW_REPO}" && breeze build-docs'