Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kjuly/sphinx-builder
Github Action to build Sphinx source files as static pages.
https://github.com/kjuly/sphinx-builder
build github-action github-pages i18n sphinx
Last synced: 18 days ago
JSON representation
Github Action to build Sphinx source files as static pages.
- Host: GitHub
- URL: https://github.com/kjuly/sphinx-builder
- Owner: Kjuly
- License: mit
- Created: 2024-05-12T12:21:45.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-05-14T13:57:21.000Z (6 months ago)
- Last Synced: 2024-05-15T17:21:46.943Z (6 months ago)
- Topics: build, github-action, github-pages, i18n, sphinx
- Language: Shell
- Homepage:
- Size: 18.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# sphinx-builder
Github Action to build Sphinx source files as static pages.
## Configurations
| Input | Default | Description
| --- | --- | ---
| source_root | docs/source | Root directory of source to build.
| build_root | docs/build | Root directory for build output.
| default_lang | en | The default language, which will be placed under the build directory, no subdirectory will be created.
| lang_mappings | '' | Newline-separated list of folder & language mappings to build (refer to [Multiple languages](#multiple-languages). If you don't provide one, will use Makefile's SOURCEDIR & BUILDDIR to determine.
## Usage
### One language only
```yaml
jobs:
build:
name: Build MkDocs Pages
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build Pages
uses: Kjuly/sphinx-builder@main
```
Folder structure:
```sh
docs/
source/
build/
```
### Multiple languages
```yaml
uses: Kjuly/sphinx-builder@main
with:
default_lang: en
lang_mappings: |-
en:en
zh-Hans:zh_CN
```
Folder structure:
```sh
docs/
source/
en/
zh-Hans/
build/
```
## Share & Override Config File
You can provide `_conf.py` to share and override `conf.py`. Below is a sample folder structure:
```sh
source/
_conf.py # Shared base config file.
requirements.txt # Optionally, you can install extra dependencies by adding this file with libs listed.
en/
_conf.py # Override config file for "en".
conf.py # The final generated config file for "en", which will be updated for each build process.
... # You don't need to provide it manually.
zh-Hans/
conf.py # No "_conf.py" provided at the same level, will use "conf.py" as it was.
...
build/
```
---
The build page will be stored in `${{ github.workspace }}/build/html`.
For output usage, please refer to [Sphinx Publisher](sphinx-publisher), which will publish to Github Pages.
[sphinx-publisher]: https://github.com/Kjuly/sphinx-publisher