From c1d98e1bb5250cd12efe2cfeb30db50f0b4c8c81 Mon Sep 17 00:00:00 2001 From: bennibbelink <79653949+bennibbelink@users.noreply.github.com> Date: Tue, 2 Apr 2024 12:27:13 -0500 Subject: [PATCH] Update Makefile and README to reflect publishing changes --- Makefile | 25 -------------- README.rst | 83 +++++++++-------------------------------------- docker/README.rst | 7 ++-- 3 files changed, 18 insertions(+), 97 deletions(-) diff --git a/Makefile b/Makefile index 3e51bdf7d..62dfea57d 100644 --- a/Makefile +++ b/Makefile @@ -30,10 +30,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" @@ -77,32 +74,10 @@ 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 - serve: html cd $(BUILDDIR) && python -m http.server diff --git a/README.rst b/README.rst index 3e4ba984e..191b281a8 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/README.rst b/docker/README.rst index 2df7da4c8..25e288f46 100644 --- a/docker/README.rst +++ b/docker/README.rst @@ -1,9 +1,6 @@ ``fuelcycle.org-deps`` 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.