Skip to content

Commit ca019df

Browse files
agriyakhetarpalagriyakhetarpal
committed
📄 Build some basic documentation
1 parent 54942c2 commit ca019df

File tree

7 files changed

+331
-0
lines changed

7 files changed

+331
-0
lines changed

‎docs/archetypes/default.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
+++
2+
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
3+
date = {{ .Date }}
4+
draft = true
5+
+++

‎docs/content/_index.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
+++
2+
title = ''
3+
date = 2024-04-06T22:34:36+05:30
4+
draft = false
5+
toc = true
6+
[cascade]
7+
type = 'docs'
8+
+++
9+
10+
# Documentation for `hugo-python-distributions`
11+
12+
This webpage is meant to serve the documentation for the `hugo-python-distributions` project, which aims to provide a distribution
13+
channel for the extended version of the Hugo static site generator through `pip`-installable binaries (wheels) hosted on the [Python Package Index (PyPI)](https://pypi.org/).
14+
15+
## Table of contents
16+
17+
- [Quickstart](#quickstart)
18+
- [Supported platforms](#supported-platforms)
19+
- [Building from sources](building-from-sources/)
20+
- [Cross-compiling for different architectures](#cross-compiling-for-different-architectures)
21+
- [macOS](#macos)
22+
- [Linux](#linux)
23+
- [Windows](#windows)
24+
25+
26+
### Quickstart
27+
28+
Create a [virtual environment](https://realpython.com/python-virtual-environments-a-primer/) and install the package (or install it globally on your system):
29+
30+
{{< tabs items="Linux/macOS,Windows" >}}
31+
32+
{{< tab >}}
33+
```bash
34+
python -m virtualenv venv
35+
source venv/bin/activate
36+
python -m pip install hugo
37+
```
38+
{{< /tab >}}
39+
40+
{{< tab >}}
41+
```powershell
42+
py -m virtualenv venv
43+
venv\Scripts\activate.bat
44+
py -m pip install hugo
45+
```
46+
{{< /tab >}}
47+
48+
{{< /tabs >}}
49+
50+
This example is using [`virtualenv`](https://virtualenv.pypa.io/en/latest/) to create a virtual environment, however, you can use any virtual environment manager of your choice. Some popular ones are the built-in [`venv`](https://docs.python.org/3/library/venv.html) module, [`virtualenvwrapper`](https://virtualenvwrapper.readthedocs.io/en/latest/), [`pipenv`](https://pipenv.pypa.io/en/latest/), [`conda`](https://docs.conda.io/en/latest/), [`poetry`](https://python-poetry.org/), [`pyenv`](https://github.com/pyenv/pyenv), [`uv`](https://github.com/astral-sh/uv), and so on.
51+
52+
This places a `hugo` installation with an executable in your virtual environment and adds an [entry point](https://packaging.python.org/en/latest/specifications/entry-points/) to it in your virtual environment's `bin` directory.
53+
54+
Then, you can use the `hugo` CLI commands as you would normally:
55+
56+
```bash
57+
hugo version
58+
hugo env --logLevel info
59+
hugo new site my-new-site
60+
hugo mod <...>
61+
hugo --printI18nWarnings --buildDrafts server
62+
```
63+
64+
and more!
65+
66+
Alternatively, you can install the package globally on your system:
67+
68+
{{< tabs items="Linux/macOS,Windows" >}}
69+
70+
{{< tab >}}
71+
```bash
72+
python3.X -m pip install hugo
73+
```
74+
{{< /tab >}}
75+
76+
{{< tab >}}
77+
```powershell
78+
py -m pip install hugo
79+
```
80+
{{< /tab >}}
81+
82+
{{< /tabs >}}
83+
84+
{{< callout emoji=✨ >}}
85+
86+
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.
87+
88+
{{</ callout >}}
89+
90+
91+
{{< tabs items="Install it as an app globally, Run it" >}}
92+
93+
{{< tab >}}
94+
```bash
95+
pipx install hugo
96+
```
97+
This installs Hugo in a separate location on your system that is isolated from your global Python environment(s).
98+
{{< /tab >}}
99+
100+
{{< tab >}}
101+
```bash
102+
pipx run hugo version
103+
pipx run hugo env --logLevel info
104+
```
105+
This runs the latest version of Hugo available on PyPI and installed through `pipx`. You can also run a specific version of Hugo through `pipx`, even if a different version is installed in whatever environment you are in:
106+
```bash
107+
pipx run hugo==0.124.1 version
108+
pipx run hugo==0.124.1 env --logLevel info
109+
```
110+
{{< /tab >}}
111+
112+
{{< /tabs >}}
113+
114+
Please refer to the [`pipx` documentation](https://pipx.pypa.io/stable/) for more information.
115+
116+
For more information on using Hugo and its command-line interface, please refer to the [Hugo documentation](https://gohugo.io/documentation/) and the [Hugo CLI documentation](https://gohugo.io/commands/).
117+
118+
### Supported platforms
119+
120+
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:
121+
122+
| Platform | Architecture | Support |
123+
| -------- | --------------- | ------------------------------- |
124+
| macOS | x86_64 (Intel) | ✅ |
125+
| macOS | arm64 (Silicon) | ✅ |
126+
| Linux | amd64 | ✅ |
127+
| Linux | arm64 | ✅ |
128+
| Windows | x86_64 | ✅ |
129+
| Windows | arm64 | 💡 Experimental support [^1] |
130+
| Windows | x86 | 💡 Experimental support [^1] |
131+
| DragonFlyBSD | amd64 | ❌ Will not receive support[^2] |
132+
| FreeBSD | amd64 | ❌ Will not receive support[^2] |
133+
| OpenBSD | amd64 | ❌ Will not receive support[^2] |
134+
| NetBSD | amd64 | ❌ Will not receive support[^2] |
135+
| Solaris | amd64 | ❌ Will not receive support[^2] |
136+
137+
[^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.
138+
139+
[^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).
140+
141+
#### Cross-compiling for different architectures
142+
143+
{{< callout type="warning" >}}
144+
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).
145+
{{</ callout >}}
146+
147+
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:
148+
149+
1. macOS for the `arm64` and `amd64` architectures via the Xcode toolchain,
150+
2. Linux for the `arm64` and `amd64` architectures via the Zig toolchain, and
151+
3. Windows for the `arm64`, and `x86` architectures via the Zig toolchain.
152+
153+
Please refer to the examples below for more information on how to cross-compile Hugo for different architectures:
154+
155+
##### macOS
156+
157+
Say, on an Intel-based (x86_64) macOS machine:
158+
159+
```bash
160+
export GOARCH="arm64"
161+
pip install . # or pip install -e .
162+
```
163+
164+
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:
165+
166+
```bash
167+
export GOARCH="amd64"
168+
pip install . # or pip install -e .
169+
```
170+
171+
##### Linux
172+
173+
First, install [Zig](https://ziglang.org/download/) on your Linux machine, and set these environment variables prior to installing the package:
174+
175+
Say, on an `amd64` Linux machine:
176+
177+
```bash
178+
export CC="zig cc -target aarch64-linux-gnu"
179+
export CXX="zig c++ -target aarch64-linux-gnu"
180+
export GOARCH="arm64"
181+
pip install . # or pip install -e .
182+
```
183+
184+
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:
185+
186+
```bash
187+
export CC="zig cc -target x86_64-linux-gnu"
188+
export CXX="zig c++ -target x86_64-linux-gnu"
189+
export GOARCH="amd64"
190+
pip install . # or pip install -e .
191+
```
192+
193+
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:
194+
195+
```bash
196+
export CC="zig cc -target x86_64-linux-musl"
197+
export CXX="zig c++ -target x86_64-linux-musl"
198+
```
199+
200+
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.
201+
202+
##### Windows
203+
204+
First, install [Zig](https://ziglang.org/download/) on your Windows machine, and set these environment variables prior to installing the package:
205+
206+
Say, on an `amd64` Windows machine:
207+
208+
```bash
209+
set CC="zig cc -target aarch64-windows-gnu"
210+
set CXX="zig c++ -target aarch64-windows-gnu"
211+
set GOARCH="arm64"
212+
pip install . # or pip install -e .
213+
```
214+
215+
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:
216+
217+
```bash
218+
set CC="zig cc -target x86-windows-gnu"
219+
set CXX="zig c++ -target x86-windows-gnu"
220+
set GOARCH="386"
221+
pip install . # or pip install -e .
222+
```
223+
224+
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.
225+
226+
> [!TIP]
227+
> 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.

‎docs/content/building-from-sources.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
+++
2+
title = 'Building from sources'
3+
date = 2024-04-06T23:28:15+05:30
4+
draft = false
5+
toc = true
6+
+++
7+
8+
Building the extended version of Hugo from source requires the following dependencies:
9+
10+
1. The [Go](https://go.dev/doc/install) toolchain
11+
2. The [Git](https://git-scm.com/downloads) version control system
12+
3. A C/C++ compiler, such as [GCC](https://gcc.gnu.org/) or [Clang](https://clang.llvm.org/)
13+
14+
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:
15+
16+
```bash
17+
choco install mingw
18+
```
19+
20+
Then, clone the repository and run the build script:
21+
22+
{{< tabs items="Linux/macOS,Windows" >}}
23+
24+
{{< tab >}}
25+
26+
```bash
27+
git clone https://github.com/agriyakhetarpal/hugo-python-distributions@main
28+
python -m venv venv
29+
source venv/bin/activate
30+
```
31+
32+
{{< /tab >}}
33+
34+
{{< tab >}}
35+
36+
```cmd
37+
git clone https://github.com/agriyakhetarpal/hugo-python-distributions@main
38+
py -m venv venv
39+
venv\Scripts\activate.bat
40+
```
41+
42+
{{< /tab >}}
43+
44+
{{< /tabs >}}
45+
46+
and then install the package in the current directory:
47+
48+
```bash
49+
pip install .
50+
```
51+
52+
or perform an editable installation via the following command:
53+
54+
```bash
55+
pip install -e .
56+
```

‎docs/content/supported-platforms.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
+++
2+
title = 'Supported platforms'
3+
date = 2024-04-06T23:27:31+05:30
4+
draft = false
5+
toc = true
6+
+++
7+
8+
Stub content for supported platforms

‎docs/go.mod‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
module github.com/agriyakhetarpal/hugo-python-distributions
2+
3+
go 1.22.0
4+
5+
require github.com/imfing/hextra v0.7.3 // indirect

‎docs/go.sum‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
github.com/imfing/hextra v0.7.3 h1:dVGA1NTcWe+FaUMdrawEypPfrrmulq5NoK0we3nC330=
2+
github.com/imfing/hextra v0.7.3/go.mod h1:cEfel3lU/bSx7lTE/+uuR4GJaphyOyiwNR3PTqFTXpI=

‎docs/hugo.yaml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
baseURL: https://agriyakhetarpal.github.io/hugo-python-distributions/
2+
languageCode: en-uk
3+
title: hugo-python-distributions
4+
5+
module:
6+
imports:
7+
- path: github.com/imfing/hextra
8+
9+
menu:
10+
main:
11+
# - name: Documentation
12+
# pageRef: /docs
13+
# weight: 1
14+
# - name: Blog
15+
# pageRef: /blog
16+
# weight: 2
17+
# - name: About
18+
# pageRef: /about
19+
# weight: 3
20+
- name: Search
21+
weight: 1
22+
params:
23+
type: search
24+
- name: View on GitHub
25+
weight: 2
26+
url: "https://github.com/agriyakhetarpal/hugo-python-distributions"
27+
params:
28+
icon: github

0 commit comments

Comments
 (0)