diff --git a/.gitignore b/.gitignore index b055998..274baeb 100644 --- a/.gitignore +++ b/.gitignore @@ -31,3 +31,4 @@ /package/*/apt/repositories/ /package/*/apt/tmp/ /package/docker/*.deb +/venv/ diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..af8659c --- /dev/null +++ b/doc/README.md @@ -0,0 +1,75 @@ + + +# Arrow Flight SQL Adapter for PostgreSQL Documentation + +This folder contains the source for the public documentation. +This is published to https://arrow.apache.org/flight-sql-postgresql/ by a GitHub Actions workflow +when changes are merged to the main branch. + +## Dependencies + +It's recommended to install build dependencies and build the documentation +inside a Python `venv`. + +To prepare building the documentation run the following on the root level of the project: + +1. Set up virtual environment if it was not already created + ```bash + python3 -m venv venv + ``` +1. Activate virtual environment + ```bash + source venv/bin/activate + ``` +1. Install documentation dependencies + ```bash + pip install -r docs/requirements.txt + ``` + +## Build & Preview + +Run the provided script to build the HTML pages. + +```bash +rake doc:html +``` + +The HTML will be generated into a `doc/build` directory. + +Preview the site on Linux by running this command. + +```bash +firefox doc/build/index.html +``` + +## Release Process + +This documentation is hosted at https://arrow.apache.org/flight-sql-postgresql/ . + +When the PR is merged to the `main` branch of the Apache Arrow Flight SQL adapter for PostgreSQL +repository, a [GitHub Actions workflow](https://github.com/apache/arrow-flight-sql-postgresql/blob/main/.github/workflows/doc.yaml) which: + +1. Builds the HTML content +2. Pushes the HTML content to the [`asf-site`](https://github.com/apache/arrow-flight-sql-postgresql/tree/asf-site) branch in this repository + +The Apache Software Foundation provides https://arrow.apache.org/, +which serves content based on the configuration in +[`.asf.yaml`](https://github.com/apache/arrow-flight-sql-postgresql/blob/main/.asf.yaml), +which specifies the target as https://arrow.apache.org/flight-sql-postgresql/. diff --git a/doc/source/_templates/trademark.html b/doc/source/_templates/trademark.html new file mode 100644 index 0000000..818b34d --- /dev/null +++ b/doc/source/_templates/trademark.html @@ -0,0 +1,30 @@ + +/* eslint-disable prettier/prettier */ + +{# Display the trademark information (which is defined in conf.py html_context). #} +{% if show_copyright and trademark %} +
+
+ +{% endif %} diff --git a/doc/source/conf.py b/doc/source/conf.py index 809f31c..6247f52 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,13 +22,21 @@ import os import pathlib import re +from datetime import datetime # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'Apache Arrow Flight SQL adapter for PostgreSQL' -copyright = '2022-2023, Apache Arrow Developers' -author = 'Apache Arrow Developers' +copyright = (f'2022-{datetime.now().year}, Apache Software Foundation\n', + "Apache Arrow Flight, Arrow Flight, Arrow Flight SQL, Apache, the Apache feather logo, and the Apache Arrow project logo", + "are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries." + ) +trademark = [ + +] +author = 'Apache Software Foundation' + version = os.environ.get('VERSION') if not version: meson_build_path = pathlib.Path(__file__).parent / '../../meson.build' @@ -96,12 +104,15 @@ ], 'use_edit_page_button': True, 'show_nav_level': 2, + "footer_start": ["copyright"], + "footer_end": ["sphinx-version", "theme-version"] } html_context = { 'github_user': 'apache', 'github_repo': 'arrow-flight-sql-postgresql', 'github_version': 'main', 'doc_path': 'doc/source', + 'trademark': trademark } html_static_path = ['_static'] html_favicon = "_static/favicon.ico"