From 3a3a6edf73e89aba97eeefbaaed53474014ccd5a Mon Sep 17 00:00:00 2001 From: Nick Budak Date: Tue, 18 Feb 2025 09:50:04 -0800 Subject: [PATCH] Centralize dependencies in a requirements.txt file This moves the python dependencies for mkdocs into a requirements.txt file so they can be installed using a single command. I ran into issues setting up local mkdocs preview because many of the needed plugins weren't installed, and it took me a minute to find where they were listed (CONTRIBUTING.md). This setup lists everything in one place so that you can install it with a single command, and CI does the same thing. Also updates the CONTRIBUTING.md file with new instructions. --- .github/workflows/ci.yml | 9 ++------- .gitignore | 3 ++- CONTRIBUTING.md | 26 +++++++++----------------- requirements.txt | 6 ++++++ 4 files changed, 19 insertions(+), 25 deletions(-) create mode 100644 requirements.txt diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1a42d097..8b9a696f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,11 +13,6 @@ jobs: - uses: actions/setup-python@v4 with: python-version: 3.x - - uses: actions/cache@v2 - with: - key: ${{ github.ref }} - path: .cache - - run: pip install mkdocs-material - - run: pip install mkdocs-table-reader-plugin - - run: pip install mkdocs-git-revision-date-localized-plugin + cache: pip + - run: pip install -r requirements.txt - run: mkdocs gh-deploy --force diff --git a/.gitignore b/.gitignore index 9c5dbf6e..d51654fd 100644 --- a/.gitignore +++ b/.gitignore @@ -8,4 +8,5 @@ site/ .sass-cache _site Gemfile.lock -node_modules \ No newline at end of file +node_modules +.python-version diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bad84e56..9c419d5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # GeoBlacklight Website Contribution Guide GeoBlacklight is a collaborative open-source project that :sparkles:welcomes:sparkles: community contributions. To contribute to the GeoBlacklight software codebase, see the [GeoBlacklight Contribution Guide](https://github.com/geoblacklight/geoblacklight/blob/main/CONTRIBUTING.md). -### Who can contribute? +## Who can contribute? **Anyone** is welcome to contribute to the GeoBlacklight website and documentation. We follow a set of contribution practices to maintain a technically sustainable and stable software project for everyone. ## Reporting an issue @@ -43,29 +43,20 @@ Since this website is edited with Markdown, the easiest way to contribute is to If you want to preview changes before committing them, follow the steps below. It may also be helpful to visit the [Material for MkDocs Getting Started page](https://squidfunk.github.io/mkdocs-material/getting-started/) for more information. -1. Open the Terminal and type the following command to install the MkDocs modules and Material theme. - - ``` - pip install mkdocs-material - ``` - -1. Install the required plugins: - +1. Clone or fork the geoblacklight.github.io repository. +1. Open a terminal in the geoblacklight.github.io directory. +1. Install python dependencies used to build the site with the following command: ``` - pip install mkdocs-table-reader-plugin - pip install mkdocs-git-revision-date-localized-plugin + pip install -r requirements.txt ``` - -1. Clone or fork the geoblacklight.github.io repository. -1. Create a new branch and publish it. -1. Change into the geoblacklight.github.io directory and type: +1. Start a local server with the following command: ``` mkdocs serve ``` - This will start a local server so you can preview the site as you build it. You will see text in the Terminal that looks something like this: + This will allow you to preview the site as you edit it. You will see text in the Terminal that looks something like this: ``` INFO - Documentation built in 4.15 seconds @@ -75,6 +66,7 @@ If you want to preview changes before committing them, follow the steps below. I ``` 1. In a browser, open the locally hosted site at http://127.0.0.1:8000/ (or whatever address your Terminal shows). +1. Create a new branch to track your changes. 1. Edit the website files and preview them in your browser. 1. When you are ready to publish the changes, commit them locally using GitHub Desktop or a Terminal command. 1. Push to the new branch. @@ -97,4 +89,4 @@ Add the `-w` flag to open a preview and automatically re-generate the diagram as - If you are uncertain about an element of your Pull Request, you can bring other contributors into the conversation by creating a comment that includes their @username. - If you like the Pull Request but want others to chime in, create a +1 comment and tag a user. -If you have questions or want to get more involved, join [GeoBlacklight Slack](https://geoblacklight.slack.com/join/shared_invite/zt-1p7dcay40-Ye_WTt5_iCqU8rDjzhkoWw#/shared-invite/email) or email the [GeoBlacklight Community](https://groups.google.com/g/geoblacklight-community) at geoblacklight-community@googlegroups.com. \ No newline at end of file +If you have questions or want to get more involved, join [GeoBlacklight Slack](https://geoblacklight.slack.com/join/shared_invite/zt-1p7dcay40-Ye_WTt5_iCqU8rDjzhkoWw#/shared-invite/email) or email the [GeoBlacklight Community](https://groups.google.com/g/geoblacklight-community) at geoblacklight-community@googlegroups.com. diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..ef99f04c --- /dev/null +++ b/requirements.txt @@ -0,0 +1,6 @@ +mkdocs +mkdocs-material +mkdocs-material-extensions +mkdocs-table-reader-plugin +mkdocs-git-revision-date-localized-plugin +pymdown-extensions