diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 00000000..682ac42c --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,46 @@ +# This file was created automatically with `myst init --gh-pages` 🪄 💚 + +name: MyST GitHub Pages Deploy +on: + push: + # Runs on pushes targeting the default branch + branches: [main] +env: + # `BASE_URL` determines the website is served from, including CSS & JS assets + # You may need to change this to `BASE_URL: /${{ github.event.repository.name }}` + BASE_URL: '' # Not required for 'projectpythia-mystmd.github.io' domain. Other repos will need to set this! + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: 'pages' + cancel-in-progress: false +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v3 + - uses: actions/setup-node@v4 + with: + node-version: 18.x + - name: Install MyST Markdown + run: npm install -g mystmd + - name: Build HTML Assets + run: myst build --html + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: './_build/html' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/.github/workflows/publish-site.yaml b/.github/workflows/publish-site.yaml deleted file mode 100644 index b2bcec23..00000000 --- a/.github/workflows/publish-site.yaml +++ /dev/null @@ -1,51 +0,0 @@ -name: publish-site - -on: - # Trigger the workflow on push to main branch - push: - branches: - - main - workflow_dispatch: - schedule: - - cron: '0 0 * * 1' # Weekly on Monday - -jobs: - automate-metrics: - runs-on: macos-latest - steps: - - uses: actions/checkout@v3 - - name: Automate Metrics - env: - PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }} - PRIVATE_KEY_ID: ${{ secrets.PRIVATE_KEY_ID }} - run: | - python -m venv analytics-api - source analytics-api/bin/activate - pip install google-analytics-data cartopy matplotlib - - python .github/workflows/get-metrics.py - python .github/workflows/write-metrics-md.py - - name: Upload zip - uses: actions/upload-artifact@v4 - with: - name: repo-zip - path: . - - build: - needs: automate-metrics - uses: ProjectPythia/cookbook-actions/.github/workflows/build-book.yaml@main - with: - environment_file: 'environment.yml' - environment_name: pythia - path_to_notebooks: 'portal' - build_command: 'make -j4 html' - build_from_code_artifact: 'true' - code_artifact_name: 'repo-zip' - workflow: '' - workflow_conclusion: '' - deploy: - needs: build - uses: ProjectPythia/cookbook-actions/.github/workflows/deploy-book.yaml@main - with: - cname: projectpythia.org - publish_dir: 'portal/_build/html' diff --git a/README.md b/README.md index 7ccb40f6..7c92c515 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,6 @@ [![nightly-build](https://github.com/ProjectPythia/projectpythia.github.io/actions/workflows/nightly-build.yaml/badge.svg)](https://github.com/ProjectPythia/projectpythia.github.io/actions/workflows/nightly-build.yaml) This is the source repository for the [Project Pythia portal](https://projectpythia.org). -The portal site is built with [sphinx](https://www.sphinx-doc.org/). +The portal site is built with [MyST-MD](https://mystmd.org/). Information on contributing is available [here](CONTRIBUTING.md) diff --git a/myst.yml b/myst.yml new file mode 100644 index 00000000..b68ee85a --- /dev/null +++ b/myst.yml @@ -0,0 +1,32 @@ +# See docs at: https://mystmd.org/guide/frontmatter +version: 1 +extends: + - https://raw.githubusercontent.com/projectpythia-mystmd/pythia-config/main/pythia.yml +project: + id: 770e49e5-344a-4c46-adaa-3afb060b2085 + # title: + # description: + keywords: [] + authors: [] + github: https://github.com/projectpythia-mystmd/projectpythia-mystmd.github.io + # bibliography: [] + + toc: + - file: portal/index.md + - file: portal/about.md + - file: portal/blog.md + - file: portal/contributing.md + - file: portal/cookbook-guide.md + - file: portal/metrics.md + - title: Posts + children: + - file: portal/posts/cookoff2023.md + - file: portal/posts/cookoff2024-savethedate.md + - file: portal/posts/cookoff2024-website.md + +site: + template: book-theme + actions: + - title: Learn More + url: https://mystmd.org/guide + domains: [] diff --git a/portal/contributing.md b/portal/contributing.md index 7b1cfce8..09a0baf5 100644 --- a/portal/contributing.md +++ b/portal/contributing.md @@ -1,6 +1,6 @@ # Project Pythia Contributor's Guide -```{Note} +```{note} This the top-level guide for Project Pythia and a great starting point for getting involved! We also have specific guides for @@ -143,7 +143,7 @@ command line tool for collaborative software version control, while GitHub is an online, web-accessible service that greatly simplifies using the powerful, yet often complex, Git. -```{Note} +```{note} GitHub operates entirely within a web browser. You do not need to install anything, but you will need to set up a free GitHub account. Git is a command line tool that is most likely already @@ -225,7 +225,7 @@ you wish to use it. Consult the repo-specific contributor’s guide for information on “Building the site”, and follow the steps described therein. -```{Note} +```{note} Repository-specific contributor's information can always be accessed by navigating your web browser to the appropriate Project Pythia GitHub repository, @@ -326,7 +326,7 @@ on this later. For further information see the [GitHub docs on forking a repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo). -```{Note} +```{note} At this point you should have a local copy of the repository in your current working directory. You can safely make changes to any of the contents. Once you are ready to contribute your changes @@ -390,7 +390,7 @@ $ git commit PATH_TO_NEW_FILE Which will prompt you for a log message. Please provide something informative. If you make lots of changes, it is best to make multiple commits, broken up into related chunks. E.g. “fixed x”, “added documentation”, “added testing”. -```{Note} +```{note} When executing `git commit` after `git add PATH_TO_NEW_FILE`, specifying the path to the new file isn't stricly necessary. However, in other instances the file path argument is required. We include it @@ -411,7 +411,7 @@ $ git status after your `commit` to verify everything looks as expected. -```{Note} +```{note} `pre-commit` _hooks_ can sometimes be difficult to satisfy. You can always tell **git** not to run the _hook_ by running `git commit --no-verify`. diff --git a/portal/cookbook-guide.md b/portal/cookbook-guide.md index f0f23962..85a6d36c 100644 --- a/portal/cookbook-guide.md +++ b/portal/cookbook-guide.md @@ -10,7 +10,7 @@ The following is a step-by-step guide to creating a new Cookbook and getting it Before you begin, ask yourself if the content you are developing for a cookbook would be better suited as an addition to an existing cookbook. The best place to discuss cookbook ideas is the [Project Pythia category of the Pangeo Discourse](https://discourse.pangeo.io/c/education/project-pythia/60). -```{Note} +```{note} These instructions assume that your goal is to contribute a new Cookbook to the community-maintained collection housed on the [Pythia Cookbook Gallery](https://cookbooks.projectpythia.org). Using the Pythia Cookbook template to create reproducible documents housed elsewhere is definitely possible! But we don't focus on that use case in this guide. @@ -39,7 +39,7 @@ Before developing your cookbook, you should consider how it will access the data Your cookbook is now ready to have content added! -```{Note} +```{note} In the rest of this guide, we assume that you are familiar with the basics of using git and GitHub. If not, we strongly recommend reading through our [GitHub tutorials in Foundations](https://foundations.projectpythia.org/foundations/getting-started-github.html). ``` @@ -54,7 +54,7 @@ However, we recommend transfering to the Pythia organization early, for a few re - Easier to get help from the Pythia infrastructure team - Encourages collaboration -```{Note} +```{note} You're still in control! You will always retain write access to your Cookbook repository even after transfering ownership to the Pythia organization. Also, _don't worry about breaking anything!_ Your repo will not affect any other Project Pythia content until you initiate the request to list it on the [Cookbook Gallery](https://cookbooks.projectpythia.org) (see below...) @@ -99,7 +99,7 @@ Your repository includes automation for building and publishing your Cookbook, p In each of these files, in the field called `environment_name:`, replace `cookbook-dev` with the name you used in your `environment.yml` file (probably `-dev`). Commit these changes. -```{Note} +```{note} If these workflow files look mysterious and you don't know anything about how GitHub Actions work, don't worry! The Pythia team will help with any problems that arise with the Cookbook automation. ``` @@ -167,7 +167,7 @@ Here's a handy trick for finding your published book: The link to your published book will then be displayed on the home page of the repo. -```{Note} +```{note} If you have transfered your repository to the ProjectPythia organization and also made a personal fork, the publishing pipeline automation will _only run on the upstream fork on the ProjectPythia organization_ so there's only one copy of the "published" book. It's possible to enable the workflows on your personal fork, but usually unneccesary if you preview your work via Pull Requests (see next section)! @@ -187,7 +187,7 @@ Not satisfied? Keep making changes! Every new push to the feature branch on your ### Building on the Pythia Binder -```{Note} +```{note} By default, notebooks are executed on the free GitHub Actions service. This works fine for most lightweight Cookbooks. If your book is building and publishing succesfully, you can safely ignore this section! ``` @@ -200,7 +200,7 @@ Here's how: - That will trigger a build and preview as usual, but the notebook execution will happen on the Binder. - If all is well, merge the changes, and all further builds will work this way. -```{Note} +```{note} The Binder uses your `environment.yml` file to create an image of an execution environment, which is stored for reuse. The time to execute your notebooks can vary, depending on whether the Binder needs to build a new image or not. ``` @@ -208,7 +208,7 @@ The Binder uses your `environment.yml` file to create an image of an execution e Once you're happy with your content and your Cookbook is building and deploying properly, it's time to think about submiting it for inclusion in the [Cookbook Gallery](https://cookbooks.projectpythia.org/)! -```{Note} +```{note} Cookbooks don't need to be "finished" in order to accepted in the Gallery! Cookbooks are typically accepted so long as they run cleanly, are free of obvious errors, and have some relevant new content. Cookbooks are meant to be living documents. We encourage authors to open GitHub issues to track progress on adding and updating content. @@ -231,7 +231,7 @@ Edit `CITATION.cff` as follows: - ORCID and other metadata for each author is optional but helpful - Under the `name:` field, change "Cookbook Template contributors" to "[Your Cookbook Name] contributors" -```{Note} +```{note} GitHub automatically tracks all contributions to your repository. The folks who help with infrastructure fixes, content reviews, etc., are considered "contributors" but not primary authors. We include the "contributors" as a single group in `CITATION.cff` to acknowledge this! ```