Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added table of content in CONTRIBUTE.md and enhanced the documentation. #897

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Added table of content in CONTRIBUTE.md and enhanced the documentation. #897

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b489a8e
Update CONTRIBUTE.md
KesharwaniArpita Nov 15, 2023
d91956c
Added table of content in CONTRIBUTE.md
KesharwaniArpita Nov 20, 2023
8b2379b
Merge branch 'apache:main' into main
KesharwaniArpita Nov 20, 2023
7d2f6e2
Merge branch 'apache:main' into main
KesharwaniArpita Dec 3, 2023
df19702
Added automated Table of Contents generation using doctoc
KesharwaniArpita Dec 3, 2023
fc12306
Removed the hand-written TOC
KesharwaniArpita Dec 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
80 changes: 40 additions & 40 deletions CONTRIBUTE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
```
Expand All @@ -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 '<[email protected]>'
git config --global user.name '<you name>'
Expand All @@ -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
```
Expand All @@ -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
```
Expand All @@ -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 [email protected]:apache/airflow-site.git
Expand All @@ -166,31 +166,31 @@ 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
lint-css Lint CSS files
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 `<ROOT DIRECTORY>/landing-pages/site` run:
To add a new blog post with pre-filled frontmatter, in `<ROOT DIRECTORY>/landing-pages/site` run:
```bash
hugo new blog/my-new-blogpost.md
```

That will create a markdown file `<ROOT DIRECTORY>/landing-pages/site/content/<LANGUAGE VERSION>/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"
Expand All @@ -199,48 +199,48 @@ 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 `<ROOT DIRECTORY>/landing-pages/site/content/<LANGUAGE VERSION>/blog/<filename>.md`.
The filename will also serve as URL for your blogpost.
To add a new blog post manually, create a markdown file in `<ROOT DIRECTORY>/landing-pages/site/content/<LANGUAGE VERSION>/blog/<filename>.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: "<blogpost title>"
linkTitle: "<blogpost link title>"
author: "<author's name>"
twitter: "<optional - author's Twitter ID>"
github: "<optional - author's Github ID>"
linkedin: "<optional - author's Linkedin ID>"
Twitter: "<optional - author's Twitter ID>"
GitHub: "<optional - author's Github ID>"
LinkedIn: "<optional - author's Linkedin ID>"
description: "<short description>"
tags: ["<tag1>", "<tag2>", ...]
date: <date in YYYY-MM-DD format>
---
```
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:

```markdown
![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 `<ROOT DIRECTORY>/landing-pages/site` run:
```bash
hugo new use-cases/my-use-case.md
```

That will create a markdown file `<ROOT DIRECTORY>/landing-pages/site/content/<LANGUAGE VERSION>/use-cases/my-use-case.md`
with following content:
with the following content:
```
---
title: "My Use Case"
Expand All @@ -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 `<ROOT DIRECTORY>/landing-pages/site/content/<LANGUAGE VERSION>/use-cases/<filename>.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:

```
---
Expand All @@ -280,7 +280,7 @@ quote:
logo: "<logo filename (with extension)>"
---
```
Below frontmatter, put your blogpost content in following format:
Below frontmatter, put your blog post content in the following format:

```
#### What was the problem?
Expand Down Expand Up @@ -324,7 +324,7 @@ logo: "my-case-study.svg"
<text>
```

### How to add a new integration
### Adding a new integration

In order to add a new integration, add an entry in `<ROOT DIRECTORY>/landing-pages/site/static/integrations.json` file,
following the format:
Expand All @@ -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 `<ROOT DIRECTORY>/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`

Expand All @@ -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:

Expand All @@ -384,20 +384,20 @@ 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;
```


### 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
Expand All @@ -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'
Expand Down
Loading