Merge pull request #358 from bennibbelink/readme-makefile-updates

Update Makefile and README to reflect new publishing procedure
cyclus · Apr 9, 2024 · 4da565f · 4da565f
2 parents 58174f3 + 06f47bd
commit 4da565f
Show file tree

Hide file tree

Showing 5 changed files with 33 additions and 124 deletions.
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    = main
-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 main branch"
-	@echo "  gh-publish-only   to push from source branch to main 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 main 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,31 +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 checkout $(GH_SOURCE_BRANCH) -- $(GH_SOURCE_DIR)
-	git reset HEAD
-	rsync -a $(BUILDDIR)/* .
-	rsync -a $(BUILDDIR)/.* .
-	git add -f `(cd $(BUILDDIR); find . -type f; cd ..)`
-	rm -rf $(GH_SOURCE_DIR) $(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 build -f docker/fuelcycle.org-deps/Dockerfile -t fuelcycle.org-deps .
-	docker run -w /cyclus.github.com -v $(PWD):/cyclus.github.com 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 `main` 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 main
-   git merge upstream/main
-   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/fuelcycle.org-deps/Dockerfile → docker/Dockerfile b/docker/fuelcycle.org-deps/Dockerfile → docker/Dockerfile
@@ -1,4 +1,3 @@
-
 FROM ghcr.io/cyclus/cymetric_22.04_apt/cymetric:latest
 
 RUN apt-get update

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/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 = main
-# 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 = main
-# GH_PUBLISH_BRANCH = gh-pages
-# GH_UPSTREAM_REPO = upstream