Merge branch 'source' into build

abachma2 · Jun 4, 2024 · 37fd6cf · 37fd6cf
2 parents 0e20c07 + 50b43a6
commit 37fd6cf
Show file tree

Hide file tree

Showing 60 changed files with 615 additions and 2,214 deletions.
diff --git a/.github/workflows/build_publish.yml b/.github/workflows/build_publish.yml
@@ -0,0 +1,45 @@
+name: Build and Publish Site
+
+on:
+  # allows us to run workflows manually
+  workflow_dispatch:
+  pull_request:
+  push:
+
+jobs:
+  build-and-upload:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Checkout cyclus.github.com
+        uses: actions/checkout@v4
+
+      - name: Build Site
+        run: |
+            make docker-html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+            path: gh-build
+
+  deploy:
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/source' }}
+    runs-on: ubuntu-latest
+    needs: build-and-upload
+
+    permissions:
+        pages: write
+        id-token: write  
+
+    environment:
+        name: github-pages
+        url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/Makefile b/Makefile
@@ -2,18 +2,17 @@
 #
 # The included file 'gh-project.mk' should define the following:
 # GH_SOURCE_DIR = top-level directory of all the ReST source files
-# GH_SOURCE_BRANCH = repository branch that contains the source
-# GH_PUBLISH_BRANCH = repository branch that contains the rendered HTML
-# GH_UPSTREAM_REPO = repository that contains the rendered HTML
 include gh-project.mk
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ./gh-build
-GIT_BRANCH    = master
-GIT_FORK      = cyclus
+CYCLUS_GIT_BRANCH    = main
+CYCLUS_GIT_FORK      = cyclus
+CYCAMORE_GIT_BRANCH	 = main
+CYCAMORE_GIT_FORK	 = cyclus
 
 
 # Internal variables.
@@ -30,10 +29,7 @@ help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  gh-preview        to build HTML in directory $BUILDDIR for testing"
 	@echo "  gh-revert         to cleanup HTML build in directory $BUILDDIR after testing"
-	@echo "  gh-publish        to build final version and push from source branch to master branch"
-	@echo "  gh-publish-only   to push from source branch to master branch, assuming already built"
 	@echo "  docker-html       to use docker to build HTML in directory $BUILDDIR for testing"
-	@echo "  docker-gh-publish to use docker to build final version and push from source branch to master branch"
 	@echo "  serve             build+serve html files using Python's SimpleHTTPServer"
 	@echo "  serve-only        serve pre-built html files using Python's SimpleHTTPServer"
 	@echo "  dirhtml           to make HTML files named index.html in directories"
@@ -59,14 +55,14 @@ gh-clean gh-revert clean:
 	-rm -rf $(BUILDDIR)
 
 gh-preview html:
-	wget -nv https://raw.githubusercontent.com/${GIT_FORK}/cyclus/${GIT_BRANCH}/INSTALL.rst -O source/user/CYCLUS_INSTALL.rst || \
-		curl https://raw.githubusercontent.com/${GIT_FORK}/cyclus/${GIT_BRANCH}/INSTALL.rst -L -o source/user/CYCLUS_INSTALL.rst
-	wget -nv https://raw.githubusercontent.com/${GIT_FORK}/cyclus/${GIT_BRANCH}/DEPENDENCIES.rst -O source/user/DEPENDENCIES.rst || \
-		curl https://raw.githubusercontent.com/${GIT_FORK}/cyclus/${GIT_BRANCH}/DEPENDENCIES.rst -L -o source/user/DEPENDENCIES.rst
-	wget -nv https://raw.githubusercontent.com/${GIT_FORK}/cycamore/${GIT_BRANCH}/INSTALL.rst -O source/user/CYCAMORE_INSTALL.rst || \
-		curl https://raw.githubusercontent.com/${GIT_FORK}/cycamore/${GIT_BRANCH}/INSTALL.rst -L -o source/user/CYCAMORE_INSTALL.rst
-	wget -nv https://raw.githubusercontent.com/${GIT_FORK}/cycamore/${GIT_BRANCH}/DEPENDENCIES.rst -O source/user/CYCAMORE_DEPS.rst || \
-		curl https://raw.githubusercontent.com/${GIT_FORK}/cycamore/${GIT_BRANCH}/DEPENDENCIES.rst -L -o source/user/CYCAMORE_DEPS.rst
+	wget -nv https://raw.githubusercontent.com/${CYCLUS_GIT_FORK}/cyclus/${CYCLUS_GIT_BRANCH}/INSTALL.rst -O source/user/CYCLUS_INSTALL.rst || \
+		curl https://raw.githubusercontent.com/${CYCLUS_GIT_FORK}/cyclus/${CYCLUS_GIT_BRANCH}/INSTALL.rst -L -o source/user/CYCLUS_INSTALL.rst
+	wget -nv https://raw.githubusercontent.com/${CYCLUS_GIT_FORK}/cyclus/${CYCLUS_GIT_BRANCH}/DEPENDENCIES.rst -O source/user/DEPENDENCIES.rst || \
+		curl https://raw.githubusercontent.com/${CYCLUS_GIT_FORK}/cyclus/${CYCLUS_GIT_BRANCH}/DEPENDENCIES.rst -L -o source/user/DEPENDENCIES.rst
+	wget -nv https://raw.githubusercontent.com/${CYCAMORE_GIT_FORK}/cycamore/${CYCAMORE_GIT_BRANCH}/INSTALL.rst -O source/user/CYCAMORE_INSTALL.rst || \
+		curl https://raw.githubusercontent.com/${CYCAMORE_GIT_FORK}/cycamore/${CYCAMORE_GIT_BRANCH}/INSTALL.rst -L -o source/user/CYCAMORE_INSTALL.rst
+	wget -nv https://raw.githubusercontent.com/${CYCAMORE_GIT_FORK}/cycamore/${CYCAMORE_GIT_BRANCH}/DEPENDENCIES.rst -O source/user/CYCAMORE_DEPS.rst || \
+		curl https://raw.githubusercontent.com/${CYCAMORE_GIT_FORK}/cycamore/${CYCAMORE_GIT_BRANCH}/DEPENDENCIES.rst -L -o source/user/CYCAMORE_DEPS.rst
 
 	PYTHONDONTWRITEBYTECODE="TRUE" $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
 	sed -i.bak 's/function top_offset([$$]node){ return [$$]node\[0\].getBoundingClientRect().top; }/function top_offset($$node){ return (typeof $$node[0] === "undefined") ? 0 : $$node[0].getBoundingClientRect().top; }/' ./gh-build/_static/cloud.js
@@ -77,29 +73,9 @@ gh-preview html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)."
 
-gh-publish-only:
-	git fetch $(GH_UPSTREAM_REPO)
-	git checkout -B $(GH_PUBLISH_BRANCH) $(GH_UPSTREAM_REPO)/$(GH_PUBLISH_BRANCH)
-	git reset HEAD
-	rsync -a $(BUILDDIR)/* .
-	rsync -a $(BUILDDIR)/.* .
-	git add -f `(cd $(BUILDDIR); find . -type f; cd ..)`
-	rm -rf  $(BUILDDIR)
-	git commit -m "Generated $(GH_PUBLISH_BRANCH) for `git log $(GH_SOURCE_BRANCH) -1 --pretty=short --abbrev-commit`" && git push --force $(GH_UPSTREAM_REPO) $(GH_PUBLISH_BRANCH)
-	git checkout $(GH_SOURCE_BRANCH)
-
-gh-publish:
-	make clean
-	make html
-	make gh-publish-only
-
 docker-gh-preview docker-html:
-	docker run -w /cyclus.github.com -v $(PWD):/cyclus.github.com cyclus/fuelcycle.org-deps bash -c "make gh-preview && chmod -R 777 $(BUILDDIR)"
-
-docker-gh-publish:
-	make clean
-	make docker-html
-	make gh-publish-only
+	docker build -f docker/Dockerfile -t site-deps .
+	docker run -w /cyclus.github.com -v $(PWD):/cyclus.github.com site-deps bash -c "make gh-preview && chmod -R 777 $(BUILDDIR)"
 
 serve: html
 	cd $(BUILDDIR) && python -m http.server

diff --git a/README.rst b/README.rst
@@ -3,17 +3,17 @@ Dependencies
 
 Building the Cyclus website requires:
 
-1. `Sphinx`_ v1.1.2 or higher
+1. `Sphinx`_ v7.2.6 or higher
 
-2. `sphinxcontrib-bibtex`_ v0.3.0 or higher
+2. `sphinxcontrib-bibtex`_ v2.6.2 or higher
 
 3. `cyclus`_
 
 4. `cymetric <https://github.com/cyclus/cymetric>`_
 
 5. `cycamore <https://github.com/cyclus/cycamore>`_
 
-6. `Cloud Sphinx Theme <https://pythonhosted.org/cloud_sptheme/index.html>`_
+6. `Cloud Sphinx Theme <https://cloud-sptheme.readthedocs.io/en/latest/index.html>`_ v1.10.1 or higher
 
 **NOTE:** The cloud package for Debian and Ubuntu is broken, so do not apt-get
 this. Please ``pip install cloud_sptheme``, ``easy_install cloud_sptheme``, or install from source instead.
@@ -24,16 +24,9 @@ to fix a bug in the package.
 Modifying the Cyclus Website
 ============================
 
-A 2 branch system has been implemented to maintain a clean process of
-rebuilding this site.
-
-1. The `source` branch contains the restructured text documents and
-Sphinx configuration used to build the site.  All direct editing of
-files should be made in the `source` branch.
-
-2. The `master` branch contains the processed and published web
-content that is derived by Sphinx from the `source` branch.  These
-files should not be editted directly.
+The site is built and published via GitHub Actions.  The default branch of this repository is `source`
+which contains the restructured text documents and Sphinx configuration used to build the site.  
+All direct editing of files should be made in the `source` branch.
 
 The rest of this readme assumes that you have two remotes associated with
 cyclus.github.com.
@@ -57,7 +50,7 @@ run::
 
 
 There are docker targets in the makefile for doing everything related to the
-site - building, previewing, and publishing.  See the ``Docker`` section below
+site - building, previewing, and testing.  See the ``Docker`` section below
 for more details.
 
 Best practice workflow for contributing to site changes
@@ -86,7 +79,7 @@ Best practice workflow for contributing to site changes
    browser.  Or if you have docker installed, you can optionally use the
    docker preview target:
 
-   ``make gh-preview-docker``
+   ``make docker-gh-preview``
 
    to build the website inside a docker container with all the correct
    dependencies and configuration taken care of automagically.
@@ -107,66 +100,22 @@ Best practice workflow for contributing to site changes
 8. Issue a pull request by going to your branch on your fork of the repo and
    clicking the "Pull Request" button.
 
-Best practice for managing a pull request
-------------------------------------------
-
-1. Synchronize your repository with the upstream repo::
-
-   git fetch upstream
-   git checkout master
-   git merge upstream/master
-   git checkout source
-   git merge upstream/source
-
-2. Checkout the `pull_request_branch` in the pull request submitter's repo::
-
-     git fetch https://github.com/[username]/cyclus.github.com pull_request_branch
-     git checkout -b pull_request_branch
-
-3. Test the changes by using the `gh-preview` target
-
-   ``make gh-preview``
-
-   This will build a version of the site in the `gh-build` directory in
-   your branch, `pull_request_branch`.  You can load it directly in a
-   local browser.
+9. Every time you modify your pull request a workflow will be triggered that builds
+   the site with your changes and uploads the built site as an artifact.  The specific workflow run 
+   can be found by viewing the "Details" of the ``build-and-upload`` check within a PR, 
+   and the ``github-pages`` artifact is listed in the "Summary".
 
-4. If satisfied, merge the `pull_request_branch` into the `source`
-   branch::
+10. If the PR is merged into the ``source`` branch the website will be published to https://fuelcycle.org 
+    automatically via GitHub Actions.
 
-     git checkout source
-     git merge pull_request_branch
-
-6. If there are no conflicts, push this to the repo
-
-   ``git push upstream source``
-
-7. Republish the pages with the `gh-publish` target.  (**NOTE: for this step,
-   the upstream Cyclus repository *must* be called `upstream`**)
-
-   ``make gh-publish``
 
 Docker
 -------
 
-The ``make docker-...`` targets require the cyclus/fuelcycle.org-deps docker image
+The ``make docker-...`` targets require the `ghcr.io/cyclus/cymetric_22.04_apt/cymetric` docker image
 which can be retrieved/updated by running::
 
-    docker pull cyclus/fuelcycle.org-deps
-
-Occasionally (i.e. for a Cyclus release) the image will need to be updated.
-This can be done by::
-
-    cd docker/fuelcycle.org-deps
-
-    # update the image the fuelcycle.org image depends on
-    docker pull cyclus/cymetric
-
-    # rebuild the image
-    docker build -t cyclus/fuelcycle.org-deps .
-
-    # push the new image to docker-hub
-    docker push cyclus/fuelcycle.org-deps
+    docker pull ghcr.io/cyclus/cymetric_22.04_apt/cymetric:latest
 
 .. _Sphinx: http://sphinx-doc.org/
 .. _sphinxcontrib-bibtex: http://sphinxcontrib-bibtex.readthedocs.org/en/latest/index.html

diff --git a/docker/Dockerfile b/docker/Dockerfile
@@ -0,0 +1,6 @@
+FROM ghcr.io/cyclus/cymetric_22.04_apt/cymetric:latest
+
+RUN apt-get update
+RUN apt-get install -y --force-yes wget python3-pip
+RUN python3 -m pip install sphinx sphinxcontrib-bibtex cloud-sptheme
+
diff --git a/docker/README.rst b/docker/README.rst
@@ -1,9 +1,6 @@
 
-``fuelcycle.org-deps`` contains a dockerfile with all dependencies for
+This directory contains a dockerfile with all dependencies for
 building the website.  This is used by the docker based build targets added to
-the makefile.  This image will need to be updated and repushed to docker hub
-periodically when dependencies for the website need updating.  Particularly,
-this image will need to be rebuilt whenever there is a new release of
-cyclus+cycamore+cymetric - otherwise new changes in those projects/repos won't
-show up/work on the website.
+the makefile.  This image will automatically use the latest cymetric image from GHCR, 
+which is updated automatically via GitHub Actions on any changes to Cyclus, Cycamore, or Cymetric.
 
diff --git a/docker/fuelcycle.org-deps/Dockerfile b/docker/fuelcycle.org-deps/Dockerfile
diff --git a/gh-project.mk b/gh-project.mk
@@ -2,17 +2,7 @@
 #
 # GH_SOURCE_DIR = top-level directory of all the ReST source files
 GH_SOURCE_DIR = source
-# GH_SOURCE_BRANCH = repository branch that contains the source
-GH_SOURCE_BRANCH = source
-# GH_PUBLISH_BRANCH = repository branch that contains the rendered HTML
-GH_PUBLISH_BRANCH = master
-# GH_UPSTREAM_REPO = repository that contains the rendered HTML
-GH_UPSTREAM_REPO = upstream
-
 
 # Example for a gh-pages project
 #
 # GH_SOURCE_DIR = doc-src
-# GH_SOURCE_BRANCH = master
-# GH_PUBLISH_BRANCH = gh-pages
-# GH_UPSTREAM_REPO = upstream
diff --git a/rever.xsh b/rever.xsh
@@ -30,10 +30,10 @@ $DOCKER_CONDA_DEPS = ['sphinx', 'numpydoc', 'cyclus', 'cycamore', 'cymetric', 'r
 $DOCKER_INSTALL_ENVVARS = {'PYTHONDONTWRITEBYTECODE': "TRUE"}
 $DOCKER_INSTALL_COMMAND = (
     'git clean -fdx && '
-    'curl https://raw.githubusercontent.com/cyclus/cyclus/master/INSTALL.rst -L -o source/user/CYCLUS_INSTALL.rst && '
-    'curl https://raw.githubusercontent.com/cyclus/cyclus/master/DEPENDENCIES.rst -L -o source/user/DEPENDENCIES.rst && '
-    'curl https://raw.githubusercontent.com/cyclus/cycamore/master/INSTALL.rst -L -o source/user/CYCAMORE_INSTALL.rst && '
-    'curl https://raw.githubusercontent.com/cyclus/cycamore/master/DEPENDENCIES.rst -L -o source/user/CYCAMORE_DEPS.rst && '
+    'curl https://raw.githubusercontent.com/cyclus/cyclus/main/INSTALL.rst -L -o source/user/CYCLUS_INSTALL.rst && '
+    'curl https://raw.githubusercontent.com/cyclus/cyclus/main/DEPENDENCIES.rst -L -o source/user/DEPENDENCIES.rst && '
+    'curl https://raw.githubusercontent.com/cyclus/cycamore/main/INSTALL.rst -L -o source/user/CYCAMORE_INSTALL.rst && '
+    'curl https://raw.githubusercontent.com/cyclus/cycamore/main/DEPENDENCIES.rst -L -o source/user/CYCAMORE_DEPS.rst && '
     'cp $(cyclus --install-path)/share/cyclus/dbtypes.json source/astatic/'
 )
 

diff --git a/source/arche/cmake.rst b/source/arche/cmake.rst
@@ -3,11 +3,11 @@
 Building Modules with CMake
 ===========================
 
-If you haven't follow the initial example in :ref:`hello_world`, you should get
+If you haven't follow the initial example in :ref:`hello_world_cpp`, you should get
 the `Cycstub repo <https://github.com/cyclus/cycstub>`_ by either `cloning the
 repository <https://github.com/cyclus/cycstub.git>`_ or by `downloading the zip
 file <https://github.com/cyclus/cycstub/archive/develop.zip>`_ (see
-:ref:`hello_world` for further instructions).
+:ref:`hello_world_cpp` for further instructions).
 
 The Cycstub repo provides a number of critical tools for building your own
 module:

diff --git a/source/arche/dre.rst b/source/arche/dre.rst
@@ -15,7 +15,7 @@ instance for each concrete ``Resource`` (i.e. ``Materials`` and ``Products``) of
 the kernel is aware. For example, there is an exchange for ``Material``
 resources and another for ``Product`` resources.
 
-The DRE is comprised of five phases which execure in series:
+The DRE is comprised of five phases which execute in series:
 
 * :ref:`rfb`
 * :ref:`rrfb`
@@ -110,13 +110,13 @@ be:
     def get_material_requests(self):
         request_qty = 10.0  # kg
         # Material Target A
-        recipe_a = self.context().get_recipe("recipeA")
+        recipe_a = self.context.get_recipe("recipeA")
         target_a = ts.Material.create_untracked(request_qty, recipe_a)
         # Material Target B
-        recipe_b = self.context().get_recipe("recipeB")
+        recipe_b = self.context.get_recipe("recipeB")
         target_b = ts.Material.create_untracked(request_qty, recipe_b)
         # commodity mapping to request target
-        commods = {"FuelA": target_a}, {"FuelB": target_b}
+        commods = {"FuelA": target_a, "FuelB": target_b}
 
         # The Python interface allow you to return a few different structures,
         # depending on your needs.  In its simplest form, if you do not not have
@@ -141,13 +141,13 @@ be:
         # a list makes them mutual requests:
         commods = [{"FuelA": target_a, "preference":2}, 
                    {"FuelB": target_b, "preference":1}]
-        port = {"commodities":commods, "constraints":request_qty
+        port = {"commodities":commods, "constraints":request_qty}
 
         # If you want the requests to be exclusive, then you have to indicate 
         # that:
         commods = [{"FuelA": target_a, "preference":2, "exclusive":True}, 
                    {"FuelB": target_b, "preference":1, "exclusive":True}]
-        port = {"commodities":commods, "constraints":request_qty
+        port = {"commodities":commods, "constraints":request_qty}
 
         # lastly, if you need to return many portfolios, simply return a list of
         # portfolio dictionaries! The "preference" and "exclusive" keys are optional

diff --git a/source/arche/hello_world_cpp.rst b/source/arche/hello_world_cpp.rst
@@ -1,4 +1,4 @@
-.. _hello_world:
+.. _hello_world_cpp:
 
 Hello, Cyclus! [C++]
 ====================