Skip to content
Permalink
Browse files
Add README.md and CONTRIBUTE.md files (#171)
  • Loading branch information
kgabryje authored and mik-laj committed Nov 15, 2019
1 parent 7230093 commit 7414308239f2099f7423accac72953ce14a6badc
Showing 4 changed files with 306 additions and 9 deletions.
@@ -0,0 +1,202 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->

## General directory structure

```bash
.
├── dist
├── docs-archive
├── landing-pages
│   ├── dist
│   ├── site
│   │   ├── assets
│ │ │ ├── icons
│ │ │ └── scss
│   │   ├── content
│ │ │ └── en
│ │ │ ├── blog
│ │ │ ├── community
│ │ │ ├── docs
│ │ │ ├── install
│ │ │ ├── meetups
│ │ │ ├── privacy-notice
│ │ │ ├── roadmap
│ │ │ └── use-cases
│   │   ├── data
│   │   ├── layouts
│   │   ├── static
│ │ │ ├── icons
│ │ │ └── integration-logos
│   │   └── themes
│ │ └── docsy
│   └── src
│   └── js
├── license-templates
└── sphinx_airflow_theme
├── demo
└── sphinx_airflow_theme
```

## Working with the project

In order to run an environment for the project, make sure that you have Docker installed. Then, use the `site.sh`
script to work with the website in a Docker container.

`site.sh` provides the following commands.

build-site Prepare dist directory with landing pages and documentation
preview-site Starts the web server with preview of the website
build-landing-pages Builds a landing pages
prepare-theme Prepares and copies files needed for the proper functioning of the sphinx theme.
shell Start shell
build-image Build a Docker image with a environment
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
cleanup Delete the virtual environment in Docker
stop Stop the environment
help Display usage

### How to add a new blogpost

In order to add a new blogpost, 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.

Then, **at the top of the file**, add frontmatter in 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>"
description: "<short description>"
tags: ["<tag1>", "<tag2>", ...]
date: <date in YYYY-MM-DD format>
---

Below frontmatter, put your blogpost content.


### How to add a new case study

In order to add a new case study, 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:

---
title: "<case study title>"
linkTitle: "<case study link title>"
quote:
text: "<quote text>"
author: "<quote author's name>"
logo: "<logo filename (with extension)>"
---

Below frontmatter, put your blogpost content in following format:

#### What was the problem?
<text>

##### How did Apache Airflow help to solve this problem?
<text>

#### What are the results?
<text>

**Important** - put the logo file in `<ROOT DIRECTORY>/landing-pages/site/static/icons/` directory. Then, in the frontmatter,
refer to it just by filename.

Example:

Path to logo file: <ROOT DIRECTORY>/landing-pages/site/static/icons/my-case-study.svg

Case study in <ROOT DIRECTORY>/landing-pages/site/content/<LANGUAGE VERSION>/use-cases/my-case-study.md

---
title: "<case study title>"
linkTitle: "<case study link title>"
quote:
text: "<quote text>"
author: "<quote author's name>"
logo: "my-case-study.svg"
---

#### What was the problem?
<text>

##### How did Apache Airflow help to solve this problem?
<text>

#### What are the results?
<text>

### How to add 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:
```json
{
"name": "<integration name>",
"url": "<url to docs with integration description>",
"logo": "</integration-logos/<filename with extension>"
}
```

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
by being displayed before integrations without a logo.

### How to add 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:

`MON, JAN 01, 6:00 PM`

If your meetup group isn't on the list, add it following the format of existing entries.

### How to release new documentation
To release a new documentation, follow these steps:

1. In Apache Airflow's website root directory, run:

<WEBSITE ROOT DIRECTORY>/site.sh prepare-theme
cd <WEBSITE ROOT DIRECTORY>/sphinx_airflow_template
pip install -e .

2. In Apache Airflow's (not website!) root directory, run:

pip install -e '.[doc]'
cd docs/
export GITHUB_VERSION="master"
make html

3. Copy generated files from `<APACHE AIRFLOW ROOT DIR>/docs/_build/html` to `<WEBSITE ROOT DIRECTORY>/docs-archive/<version>/`

4. Make a commit with generated documentation only.

5. To generate full website with documentation, run:

<WEBSITE ROOT DIRECTORY>/site.sh build-site
@@ -0,0 +1,68 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->

Apache Airflow website
======================

[![Build Status](https://travis-ci.org/apache/airflow-site.svg?branch=aip-11)](https://travis-ci.org/apache/airflow-site)

This is a repository of [Apache Airflow website](https://airflow.apache.org).
The repository of Apache Airflow can be found [here](https://github.com/apache/airflow/).

# General directory structure

- docs-archive - directory containing archived documentation versions and shell script generating docs index,
- landing-pages - directory containing the source code of landing pages,
- license-templates - directory containing license templates,
- sphinx_airflow_theme - directory containing source code of sphinx theme for Apache Airflow documentation site.

For more detailed description of directory structure, please refer to [contributor's guide](CONTRIBUTE.md).

# Getting started

If you're a Macbook user, first install `coreutils`.

`brew install coreutils`

---

The Docsy theme required for the site to work properly is included as a git submodule.
Hence, to clone the repository correctly, run the following command:

`git clone --recurse-submodules git@github.com:apache/airflow-site.git`

or

`git clone --recurse-submodules https://github.com/apache/airflow-site.git`

---

In order to build site, run script `<ROOT DIRECTORY>/site.sh build-site`.

In order to preview landing pages, run script `<ROOT DIRECTORY>/site.sh preview`.

In order to work with documentation theme, please refer to
[Sphinx Airflow theme's readme file](sphinx_airflow_theme/README.md).

For more detailed description of `site.sh` capabilities, please refer to [contributor's guide](CONTRIBUTE.md).

# [Contributor's guide](CONTRIBUTE.md)

If you'd like to contribute to the Apache Airflow website project, read our [contributor's guide](CONTRIBUTE.md)
where you can find detailed instructions on how to work with the website.
15 site.sh
@@ -32,19 +32,18 @@ usage: ${0} <command> [<args>]
These are ${0} commands used in various situations:
stop Stop the environment
cleanup Delete the virtual environment in Docker
build-image Build a Docker image with a environment
install-node-deps Download all the Node dependencies
build-site Prepare dist directory with landing pages and documentation
preview-site Starts the web server with preview of the website
preview-docs Starts the web server with preview of the Sphinx theme
prepare-theme Prepares and copies files needed for the proper functioning of the sphinx theme.
build-landing-pages Builds a landing pages
build-site Prepare dist directory with landing pages and documentation
prepare-theme Prepares and copies files needed for the proper functioning of the sphinx theme.
shell Start shell
build-image Build a Docker image with a environment
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
shell Start shell
cleanup Delete the virtual environment in Docker
stop Stop the environment
help Display usage
Unrecognized commands are run as programs in the container.
@@ -17,4 +17,32 @@
under the License.
-->

# Sphinx theme for Airflow
Sphinx theme for Airflow
========================

Sphinx theme for Apache Airflow website.

# Getting started

In order to start working with the theme, please follow the instructions below.
1. Make sure that your `python` shell command executes Python3 interpreter. If necessary, use a virtual environment:

`mkvirtualenv -p python3 <name_of_environment>`

2. To make Javascript and CSS code available for the theme, run the following command in the root directory:

`./site.sh build-site && ./site.sh prepare-theme`

3. To install the required Python packages, in `<ROOT DIRECTORY>/sphinx_airflow_theme` run:

`pip install -e .`

4. To launch the demo documentation page, in `<ROOT DIRECTORY>/sphinx_airflow_theme/demo` run:
`./docs.sh build && ./docs.sh preview`

# Theme's source files

- `<ROOT DIRECTORY>/sphinx_airflow_theme/sphinx_airflow_theme` - HTML files
- `<ROOT DIRECTORY>/landing-pages/site/assets/scss` - SCSS files
- `<ROOT DIRECTORY>/landing-pages/src/js` - Javascript files. If you create a new JS file, **don't forget to include it
in** `<ROOT DIRECTORY>/landing-pages/src/docs-index.js

0 comments on commit 7414308

Please sign in to comment.