-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1 from spebt/sphinx-book
Sphinx book
- Loading branch information
Showing
55 changed files
with
1,437 additions
and
974 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,37 @@ | ||
name: sphinx-documentation-html | ||
|
||
on: | ||
push: | ||
branches: | ||
- main # Set a branch name to trigger deployment | ||
pull_request: | ||
|
||
jobs: | ||
deploy: | ||
runs-on: ubuntu-latest | ||
permissions: | ||
contents: write | ||
concurrency: | ||
group: ${{ github.workflow }}-${{ github.ref }} | ||
|
||
steps: | ||
- uses: actions/checkout@v4 | ||
- uses: actions/setup-python@v5 | ||
with: | ||
python-version: '3.12' | ||
cache: 'pip' # caching pip dependencies | ||
|
||
- name: Setup Python dependencies | ||
run: pip install sphinx myst-parser sphinx-design pydata-sphinx-theme | ||
|
||
- name: Sphinx build | ||
run: | | ||
cd docs | ||
make html | ||
- name: Deploy | ||
uses: peaceiris/actions-gh-pages@v4 | ||
if: github.ref == 'refs/heads/main' | ||
with: | ||
github_token: ${{ secrets.GITHUB_TOKEN }} | ||
publish_dir: docs/build |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,2 @@ | ||
_site | ||
.sass-cache | ||
.jekyll-cache | ||
.jekyll-metadata | ||
vendor | ||
Gemfile.lock | ||
build | ||
.vscode |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
SPHINXOPTS ?= | ||
SPHINXBUILD ?= sphinx-build | ||
SOURCEDIR = source | ||
BUILDDIR = build | ||
|
||
# Put it first so that "make" without argument is like "make help". | ||
help: | ||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: help Makefile | ||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new | ||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
%: Makefile | ||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,43 +1,57 @@ | ||
# spebt.github.io | ||
SPEBT Project GitHub organization website files | ||
# SPEBT Project Documentation | ||
|
||
## Documentation Generation | ||
|
||
This website is generated by Sphinx with \"PyData Sphinx Theme\" | ||
required Python packages: | ||
|
||
## Webpage Generation | ||
This website is generated by Jekyll with "minima" theme. | ||
``` zsh | ||
sphinx | ||
pydata-sphinx-theme | ||
sphinx_design | ||
myst_parser | ||
``` | ||
|
||
## Develop the site locally | ||
### Develop the site locally | ||
|
||
1. Setup Jekyll local develop environment locally | ||
|
||
Check out [this GitHub Docs tutorial](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll). | ||
> [!TIP] | ||
> For easy management of the *Python* packages, it is recommended to use a virtual environment. | ||
> I recommand using `conda` and *Miniconda* should be sufficient for this purpose. | ||
> Check out the [Miniconda | ||
documentation](https://docs.anaconda.com/miniconda/) for more | ||
information. | ||
|
||
1. Clone or download the website code from GitHub: | ||
|
||
[https://github.com/spebt/spebt.github.io](https://github.com/spebt/spebt.github.io) | ||
1. Install the required Python packages: | ||
|
||
1. Change the contents as is needed with your favorite editor | ||
|
||
- Install the ruby dependency by | ||
```zsh | ||
bundle install | ||
``` | ||
``` shell | ||
pip install sphinx pydata-sphinx-theme sphinx_design myst_parser | ||
``` | ||
|
||
2. Clone or download the website code from GitHub: | ||
|
||
<https://github.com/spebt/spebt.github.io> | ||
|
||
Tips: Live reload | ||
3. Change the contents as is needed with your favorite editor. | ||
> [!TIP] | ||
> Popular editors: | ||
> - [Visual Studio Code](https://code.visualstudio.com/) | ||
> - [Neovim](https://neovim.io/) | ||
|
||
Run | ||
```zsh | ||
bundle exec jekyll serve --livereload | ||
1. Run the following command to build the website: | ||
|
||
``` shell | ||
make html | ||
``` | ||
|
||
## Deploy to GitHub page | ||
|
||
- Use `git` to commit your tested changes and push to the remote repository. | ||
- GitHub Actions will take over the rest. | ||
|
||
2. Open the generated HTML `index.html` in the `build` directory with | ||
your browser (e.g. *google chrome*). | ||
|
||
### Deploy to GitHub page | ||
|
||
Author: | ||
Fang Han, [email protected] | ||
- Use `git` to commit your tested changes and push to the remote | ||
repository. | ||
- GitHub Actions will take over the rest. | ||
|
||
## Contributors | ||
|
||
Generated by Jekyll, with Minima-2.5 theme | ||
[SPEBT GitHub Porject Contributors](pages/contributors.html) |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.