diff --git a/Makefile b/Makefile index 3e51bdf7..2406488b 100644 --- a/Makefile +++ b/Makefile @@ -2,9 +2,6 @@ # # 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. @@ -12,8 +9,10 @@ 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 ' where 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 index 3e4ba984..191b281a 100644 --- a/README.rst +++ b/README.rst @@ -3,9 +3,9 @@ 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`_ @@ -13,7 +13,7 @@ Building the Cyclus website requires: 5. `cycamore `_ -6. `Cloud Sphinx Theme `_ +6. `Cloud Sphinx Theme `_ 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 b/docker/Dockerfile similarity index 99% rename from docker/fuelcycle.org-deps/Dockerfile rename to docker/Dockerfile index ffacd3a4..9a16891a 100644 --- a/docker/fuelcycle.org-deps/Dockerfile +++ b/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 index 2df7da4c..ed322ae0 100644 --- 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 index 8525ad49..01631c8d 100644 --- 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