Move documentation to separate website

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   push:
     branches:
       - main
+  schedule:
+    - cron: '0 0 * * sun'
+    - cron: '0 12 * * wed'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -254,3 +257,52 @@ jobs:
           echo -e '```\n' >> $GITHUB_STEP_SUMMARY
           (cd output/wheel && tree -a * | sed 's/^/    /' | tee -a $GITHUB_STEP_SUMMARY)
           echo -e '\n```\n' >> $GITHUB_STEP_SUMMARY
+
+  # FIXME: when ready, move this to a separate workflow or make it run on
+  # just the main branch (after a PR is merged)
+  docs:
+    needs: [style]
+    name: documentation-build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633  # v4.1.2
+        with:
+          fetch-depth: 0
+          submodules: 'recursive'
+      - uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491  # v5.0.0
+        id: setup-go
+        with:
+          go-version: "1.22.1"
+          cache: false
+          check-latest: true
+      - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d  # v5.1.0
+        with:
+          python-version: 3.12
+
+      - name: Restore cache for Hugo
+        uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9  # v4.0.2
+        with:
+          path: ./hugo_cache/
+          # This should pick up the same cache as the build_wheels job
+          key: ubuntu-latest-hugo-${{ steps.setup-go.outputs.go-version }}
+
+      - name: Install Hugo
+        run: pip install -e .
+
+        # TODO: refactor to use nox or just remove nox later
+      - name: Build documentation website
+        run: |
+          cd docs
+          hugo --minify
+
+      - name: Deploy documentation website
+        uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847  # v3.9.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/public/
+          publish_branch: gh-pages
+          user_name: "agriyakhetarpal"
+          user_email: "74401230+agriyakhetarpal@users.noreply.github.com"
+          keep_files: false

.gitignore

@@ -184,3 +184,8 @@ hugo_cache/
 
 # Hugo version file
 hugo/VERSION
+
+# Documentation
+/docs/public
+/docs/resources
+*.lock

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/themes/docura"]
+	path = docs/themes/docura
+	url = https://github.com/docura/docura.git

MANIFEST.in

@@ -1,5 +1,6 @@
 graft hugo
 prune scripts
+prune docs
 
 include LICENSE LICENSE-hugo.txt README.md CODE_OF_CONDUCT.md SECURITY.md pyproject.toml setup.py setup.cfg
 exclude hugo/binaries/hugo-*

README.md

@@ -43,7 +43,7 @@ This project provides wheels for [Hugo](https://gohugo.io/) so that it can be us
 
 This project, `hugo` is versioned alongside the Hugo releases and is aligned with the versioning of Hugo itself, which uses `SemVer` – but is likely versioned according to [0ver](https://0ver.org/) software standards based on their [versioning history](https://github.com/gohugoio/hugo/releases).
 
-Binaries for `hugo` through these wheels are available for Hugo versions **0.121.2** and above, through PyPI or through releases on GitHubr. If you need an older version of `hugo` that is not available through this package, please consider using the [official Hugo binaries](https://github.com/gohugoio/hugo/releases).
+Binaries for `hugo` through these wheels are available for Hugo versions **0.121.2** and above, through PyPI or through releases on GitHub. If you need an older version of `hugo` that is not available through this package, please consider using the [official Hugo binaries](https://github.com/gohugoio/hugo/releases).
 
 Please refer to the section on [Supported platforms](#supported-platforms) for a list of wheels available for supported platforms and architectures. If it does, jump to the [Quickstart](#quickstart) section to get started.
 
@@ -52,198 +52,7 @@ Please refer to the section on [Supported platforms](#supported-platforms) for a
 
 ## Documentation
 
-### Quickstart
-
-Create a virtual environment and install the package (or install it globally on your system):
-
-```bash
-python -m virtualenv venv  # (or your preferred method of creating virtual environments)
-pip install hugo
-```
-
-This places a `hugo` installation with an executable in your virtual environment and adds an entry point to it in your virtual environment's `bin` directory. You can use the `hugo` command as you would normally:
-
-```bash
-hugo version
-hugo env --logLevel info
-```
-
-Alternatively, you can install the package globally on your system:
-
-```bash
-python3.X -m pip install hugo  # Unix
-py -m pip install hugo         # Windows
-```
-
-> [!TIP]
-> It is a great idea to use [`pipx`](https://github.com/pypa/pipx) to install or use Hugo in an isolated location without having to create a virtual environment, which will allow you to run Hugo as a command-line tool without having to install it globally on your system. i.e.,
-```bash
-pipx install hugo      # install and run Hugo through pipx
-```
-or
-```bash
-pipx run hugo==0.121.2 # run a specific version of Hugo through pipx, even if a different version is installed in whatever environment you are in
-```
-Please refer to the [`pipx` documentation](https://pipx.pypa.io/stable/) for more information.
-
-Then, you can use the `hugo` commands as you would normally:
-
-```bash
-hugo version
-hugo env --logLevel info
-```
-
-and
-
-```bash
-hugo new site mysite
-hugo --printI18nWarnings server
-# and so on
-...
-```
-
-Standard virtual environments can allow multiple versions of Hugo to be installed and used side-by-side. To use a specific version of Hugo, you can specify the version when installing the package (please refer to the section [_What version of `hugo` do I install?_](#what-version-of-hugo-do-i-install) for more information):
-
-```bash
-pip install "hugo==0.X.Y"
-```
-
-For more information on using Hugo and its command-line interface, please refer to the [Hugo documentation](https://gohugo.io/documentation/) and [Hugo CLI documentation](https://gohugo.io/commands/).
-
-### Supported platforms
-
-A subset of the platforms supported by Hugo itself are supported by these wheels for `hugo` via `hugo-python-distributions`. The plan is to support as many platforms as possible with Python wheels and platform tags. Please refer to the following table for a list of supported platforms and architectures:
-
-| Platform | Architecture    | Support                         |
-| -------- | --------------- | ------------------------------- |
-| macOS    | x86_64 (Intel)  | ✅                              |
-| macOS    | arm64 (Silicon) | ✅                              |
-| Linux    | amd64           | ✅                              |
-| Linux    | arm64           | ✅                              |
-| Windows  | x86_64          | ✅                              |
-| Windows  | arm64           | 💡 Experimental support [^1]    |
-| Windows  | x86             | 💡 Experimental support [^1]    |
-| DragonFlyBSD | amd64       | ❌ Will not receive support[^2] |
-| FreeBSD  | amd64           | ❌ Will not receive support[^2] |
-| OpenBSD  | amd64           | ❌ Will not receive support[^2] |
-| NetBSD   | amd64           | ❌ Will not receive support[^2] |
-| Solaris  | amd64           | ❌ Will not receive support[^2] |
-
-[^1]: Support for 32-bit (i686) and arm64 architectures on Windows is made possible through the use of the [Zig compiler toolchain](https://ziglang.org/) that uses the LLVM ecosystem. These wheels are experimental owing to the use of `cibuildwheel` and cross-compilation and may not be stable or reliable for all use cases, and are not officially supported by the Hugo project at this time. Please refer to the [Building from source](#building-from-source) section for more information on how to build Hugo for these platforms and architectures, since these wheels are not currently pushed to PyPI for general availability – however, they are tested regularly in CI. If you need support for these platforms, please consider building from source or through a CI provider.
-
-[^2]: Support for these platforms is not possible to include because of i. the lack of resources to test and build for them and ii. the lack of support for these platform specifications in Python packaging standards and tooling. If you need support for these platforms, please consider downloading the [official Hugo binaries](https://github.com/gohugoio/hugo/releases)
-
-### Building from source
-
-Building the extended version of Hugo from source requires the following dependencies:
-
-- The [Go](https://go.dev/doc/install) toolchain
-- The [Git](https://git-scm.com/downloads) version control system
-- A C/C++ compiler, such as [GCC](https://gcc.gnu.org/) or [Clang](https://clang.llvm.org/)
-
-Windows users can use the [Chocolatey package manager](https://chocolatey.org/) in order to use the [MinGW compiler](https://chocolatey.org/packages/mingw). After installing Chocolatey, run the following command in an elevated terminal prompt:
-
-```bash
-choco install mingw
-```
-
-Then, clone the repository and run the build script:
-
-```bash
-git clone https://github.com/agriyakhetarpal/hugo-python-distributions@main
-python -m venv venv
-source venv/bin/activate      # on Unix-based systems
-venv\Scripts\activate.bat     # on Windows
-pip install -e .              # editable installation
-pip install .                 # regular installation
-```
-
-#### Cross-compiling for different architectures
-
-> [!NOTE]
-> Cross-compilation is experimental and may not be stable or reliable for all use cases. If you encounter any issues with cross-compilation, please feel free to [open an issue](https://github.com/agriyakhetarpal/hugo-python-distributions/issues/new).
-
-This project is capable of cross-compiling Hugo binaries for various platforms and architectures and it can be used as follows. Cross-compilation is provided for the following platforms:
-
-1. macOS for the `arm64` and `amd64` architectures via the Xcode toolchain,
-2. Linux for the `arm64` and `amd64` architectures via the Zig toolchain, and
-3. Windows for the `arm64`, and `x86` architectures via the Zig toolchain.
-
-Please refer to the examples below for more information on how to cross-compile Hugo for different architectures:
-
-##### macOS
-
-Say, on an Intel-based (x86_64) macOS machine:
-
-```bash
-export GOARCH="arm64"
-pip install .  # or pip install -e .
-```
-
-This will build a macOS `arm64` binary distribution of Hugo that can be used on Apple Silicon-based (`arm64`) macOS machines. To build a binary distribution for the _target_ Intel-based (`x86_64`) macOS platform on the _host_ Apple Silicon-based (`arm64`) macOS machine, you can use the following command:
-
-```bash
-export GOARCH="amd64"
-pip install .  # or pip install -e .
-```
-
-##### Linux
-
-First, install [Zig](https://ziglang.org/download/) on your Linux machine, and set these environment variables prior to installing the package:
-
-Say, on an `amd64` Linux machine:
-
-```bash
-export CC="zig cc -target aarch64-linux-gnu"
-export CXX="zig c++ -target aarch64-linux-gnu"
-export GOARCH="arm64"
-pip install .  # or pip install -e .
-```
-
-will cross-compile a Linux arm64 binary distribution of Hugo that can be used on the targeted arm64 Linux machines. To build a binary distribution for the _target_ `amd64` Linux platform on the _host_ `arm64` Linux machine, set the targets differently:
-
-```bash
-export CC="zig cc -target x86_64-linux-gnu"
-export CXX="zig c++ -target x86_64-linux-gnu"
-export GOARCH="amd64"
-pip install .  # or pip install -e .
-```
-
-This creates dynamic linkage for the built Hugo binary with a system-provided GLIBC. If you wish to statically link the binary with MUSL, change the `CC` and `CXX` environment variables as follows:
-
-```bash
-export CC="zig cc -target x86_64-linux-musl"
-export CXX="zig c++ -target x86_64-linux-musl"
-```
-
-Linkage against MUSL is not tested in CI at this time, but it should work in theory. The official Hugo binaries do not link against MUSL for a variety of reasons including but not limited to the size of the binary and the popularity of the GLIBC C standard library and its conventions.
-
-##### Windows
-
-First, install [Zig](https://ziglang.org/download/) on your Windows machine, and set these environment variables prior to installing the package:
-
-Say, on an `amd64` Windows machine:
-
-```bash
-set CC="zig cc -target aarch64-windows-gnu"
-set CXX="zig c++ -target aarch64-windows-gnu"
-set GOARCH="arm64"
-pip install .  # or pip install -e .
-```
-
-will cross-compile a Windows `arm64` binary distribution of Hugo that can be used on the targeted `arm64` Windows machines (note the use of `set` instead of `export` on Windows), and so on for the `x86` architecture:
-
-```bash
-set CC="zig cc -target x86-windows-gnu"
-set CXX="zig c++ -target x86-windows-gnu"
-set GOARCH="386"
-pip install .  # or pip install -e .
-```
-
-For a list of supported distributions for Go, please run the `go tool dist list` command on your system. For a list of supported targets for Zig, please refer to the [Zig documentation](https://ziglang.org/documentation/) for more information or run the `zig targets` command on your system.
-
-> [!TIP]
-> Cross-compilation for a target platform and architecture from a different host platform and architecture is also possible, but it remains largely untested at this time. Currently, the [Zig compiler toolchain](https://ziglang.org/) is known to work for cross-platform, cross-architecture compilation.
+The documentation for this project is available at [https://agriyakhetarpal.github.io/hugo-python-distributions/](https://agriyakhetarpal.github.io/hugo-python-distributions/)
 
 ### Background
 

docs/archetypes/default.md

@@ -0,0 +1,5 @@
++++
+title = '{{ replace .File.ContentBaseName "-" " " | title }}'
+date = {{ .Date }}
+draft = true
++++