Merge pull request #1 from spebt/sphinx-book

Sphinx book

.github/workflows/sphinx-doc-gh-pages.yml

@@ -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

.gitignore

@@ -1,7 +1,2 @@
-_site
-.sass-cache
-.jekyll-cache
-.jekyll-metadata
-vendor
-Gemfile.lock
+build
 .vscode

Makefile

@@ -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)

README.md

@@ -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)