Merge pull request #592 from hackforla/feat/fix-mkdocs

Feat/fix mkdocs

.github/workflows/mkdocs-build.yml

@@ -1,28 +1,43 @@
-name: CI for MkDocs
-on:
-  push:
-    branches:
-      - develop
-permissions:
-  contents: write
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-      - run: pip install mkdocs-material
-      - run: mkdocs gh-deploy --force
+name: Build MkDocs site (develop)
+
+on:
+  push:
+    branches:
+      # TODO: change to main when we merge develop to main
+      - develop
+    paths:
+      - "mkdocs/**/**.md"
+      - "mkdocs/mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    if: github.actor != 'github-actions[bot]'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Install Dependencies
+        run: pip install \
+          mkdocs-material==9.1.17 \
+          mkdocs-autolinks-plugin==0.7.1
+      - name: Publish docs
+        run: |
+          cd mkdocs
+          mkdocs gh-deploy --force

docker-compose.docs.yml

@@ -0,0 +1,16 @@
+name: civic-tech-jobs-mkdocs
+
+services:
+  mkdocs:
+    container_name: mkdocs
+    image: hackforlaops/mkdocs:latest
+    command: mkdocs serve -a "0.0.0.0:8005"
+    ports:
+      - "8005:8005"
+    volumes:
+      - ./mkdocs:/app
+    develop:
+      watch:
+        - action: sync
+          path: ./mkdocs
+          target: /app

frontend/src/tw-components/CookieBanner.tsx

@@ -27,7 +27,7 @@ function CookieBanner(props: CookieBannerProps) {
       aria-label="cookies banner"
       className={`${
         hidden ? "hidden" : ""
-      } fixed flex flex-col bottom-12 left-1/2 transform -translate-x-1/2 bg-white w-3/4 p-4 z-50 rounded-lg shadow-2xl shadow-inner`}
+      } fixed flex flex-col bottom-12 left-1/2 transform -translate-x-1/2 bg-white w-3/4 p-4 z-50 rounded-lg shadow-2xl`}
     >
       <div className="min-h-48 max-h-64 justify-between space-y-5 p-6">
         <div className="flex flex-row justify-between items-center">

mkdocs/docs/developer/mkdocs-architecture.md

@@ -0,0 +1,196 @@
+# MKdocs Architecture
+
+```yml
+├── .github/
+│   ├── ISSUE_TEMPLATE/
+│   └── workflows/
+│       └── mkdocs-build.yml # Docs
+├── backend/
+├── dev/
+├── frontend/
+├── mkdocs/ # Docs
+│   ├── docs/
+│   └── mkdocs.yml # Docs
+├── .dockerignore
+├── .gitignore
+├── CONTRIBUTING.md
+├── docker-compose.yml
+├── docker-compose.docs.yml # Docs
+├── LICENSE
+└── README.md
+```
+
+_<p style="text-align: center;">Overall project structure</p>_
+
+```yml
+├── docs/
+│   ├── assets/
+│   ├── css/
+│   ├── developer/
+│   ├── joining-the-team/
+│   ├── js/
+│   └── misc/
+├── index.md
+├── resources.md
+├── mkdocs.yml
+```
+
+_<p style="text-align: center;">mkdocs directory structure</p>_
+
+### Summary
+
+The MkDocs "sub-project" lives in the `mkdocs/` folder. A development server can be run using the `docker-compose.docs.yml` compose script. The mkdocs is set to automatically deploy to github pages using the `mkdocs-build.yml` github action.
+
+
+### Docker MkDocs
+
+It is important to note that we are using Hack for LA's prebuilt docker mkdocs image for convenient setup. Please see the resources below for more information:
+
+- [Hack for LA - docker-mkdocs repo](https://github.com/hackforla/docker-mkdocs)
+- [Hack for LA - docker-mkdocs documentation](https://hackforla.github.io/docker-mkdocs/)
+- [Hack for LA - docker-mkdocs dockerhub image](https://hub.docker.com/r/hackforlaops/mkdocs)
+
+This prebuilt docker image makes it easy to get a mkdocs development server running with one command, without having to install python or mkdocs dependencies on your local machine. It also includes common useful plugins that we dont have to worry about installing ourselves, and already includes the `mkdocs-material` theme pre-installed.
+
+Our project implements the HFLA mkdocs image by pulling it inside the `docker-compose.docs.yml` file:
+
+```yml
+name: civic-tech-jobs-mkdocs
+
+services:
+  mkdocs:
+    container_name: mkdocs
+    image: hackforlaops/mkdocs:latest
+    command: mkdocs serve -a "0.0.0.0:8005"
+    ports:
+      - "8005:8005"
+    volumes:
+      - ./mkdocs:/app
+    develop:
+      watch:
+        - action: sync
+          path: ./mkdocs
+          target: /app
+```
+
+Now when we run docker compose up like so:
+
+```sh
+docker-compose -f docker-compose.docs.yml up --watch
+```
+
+A mkdocs development server is started on `http://localhost:8005`
+
+### MkDocs Deployment
+
+The url for the github pages site is: `https://hackforla.github.io/CivicTechJobs/` (the website you are reading this on right now).
+
+Our github repo is set to publish the docs to Github Pages using the `gh-pages` branch. This setting can be configured in the project's [Pages settings](https://github.com/hackforla/CivicTechJobs/settings/pages).
+
+External Resources:
+
+- [MkDocs Documentation | deployment instructions](https://www.mkdocs.org/user-guide/deploying-your-docs/)
+- [Github Pages documentation](https://docs.github.com/en/pages/quickstart)
+
+Relevant PR and Issue:
+
+- [Fix mkdocs deployment #456](https://github.com/hackforla/CivicTechJobs/issues/456)
+- [Feat/fix mkdocs #592](https://github.com/hackforla/CivicTechJobs/pull/592)
+
+The docs are set to automatically deploy to github pages using the `mkdocs-build.yml` github action. This action builds the mkdocs and saves the static files into the `gh-pages` branch.
+
+### Github Action for mkdocs deployment
+
+```yml
+name: Build MkDocs site (develop)
+
+on:
+  push:
+    branches:
+      - develop
+    paths:
+      - "mkdocs/**/**.md"
+      - "mkdocs/mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    if: github.actor != 'github-actions[bot]'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Install Dependencies
+        run: pip install \
+          mkdocs-material==9.1.17 \
+          mkdocs-autolinks-plugin==0.7.1
+      - name: Publish docs
+        run: |
+          cd mkdocs
+          mkdocs gh-deploy --force
+```
+
+Workflow Overview
+
+- `name: Build MkDocs site` - The name of this workflow is "Build MkDocs site."
+- `on: push: - develop` - The workflow is triggered when there’s a push to the develop branch. (We will change this to `main` later)
+- `paths: ...` - The workflow will only run if the files being pushed are Markdown files (`.md`) or the `mkdocs.yml` configuration file inside the mkdocs directory.
+- `workflow_dispatch:` - This allows manual triggering of the workflow via the GitHub Actions interface.
+- `permissions: contents: write` - This grants the action permission to write contents to the repository. It's needed for deploying the site, which requires pushing to the `gh-pages` branch.
+- `runs-on: ubuntu-latest` - This specifies that the job will run on the latest Ubuntu environment provided by GitHub Actions.
+- `if: github.actor != 'github-actions[bot]'` - This condition ensures that the job doesn’t trigger if the GitHub Actions bot is the one making the changes. This prevents infinite loops where the action keeps triggering itself.
+- `uses: actions/checkout@v4` - This step checks out the repository code so the workflow can access the files.
+- `run: git config user.name github-actions[bot]` - Configures Git to use the `github-actions[bot]` user for any commits or pushes that may happen during the deployment.
+- `git config user.email 41898282+github-actions[bot]@users.noreply.github.com` - Sets the email for the github-actions[bot] user.
+- `uses: actions/setup-python@v5` - This sets up a Python environment in the GitHub runner, which is necessary for installing and running MkDocs.
+
+Set environment variable for caching
+
+- `run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV`
+- This step sets an environment variable called `cache_id` to the current week of the year (`%V`). This value will be used as the key for caching to ensure that the cache is updated weekly.
+
+Cache dependencies
+
+- `uses: actions/cache@v4` - This step caches dependencies (to speed up future builds) in the .cache directory.
+- `with: key: mkdocs-material-${{ env.cache_id }}` - The cache key is based on the cache_id, so the cache is refreshed weekly.
+- `path: .cache` - Specifies that the cache should be stored in the .cache directory.
+- `restore-keys: mkdocs-material-` - This allows for fallback caching if an exact cache match is not found.
+
+Install Dependencies
+
+- `run: pip install mkdocs-material==9.1.17 mkdocs-autolinks-plugin==0.7.1`
+- This installs the necessary dependencies for MkDocs to work. In this case:
+- `mkdocs-material==9.1.17`: A popular theme for MkDocs.
+- `mkdocs-autolinks-plugin==0.7.1`: A plugin that automatically creates links between pages in your documentation based on their titles.
+
+Publish Documentation
+
+- `run: cd mkdocs && mkdocs gh-deploy --force`
+- first it changes to the `mkdocs/` directory.
+- then it deploys the MkDocs site to GitHub Pages using `mkdocs gh-deploy --force`. The `--force` flag ensures that the contents of the GitHub Pages branch (`gh-pages`) are overwritten with the latest deployment.
+
+##### Summary
+This workflow automates the process of building and deploying a MkDocs site when changes are pushed to the develop branch. It does the following:
+
+1. Checks out the repository and configures Git for pushing changes.
+2. Sets up Python and installs the necessary MkDocs dependencies.
+3. Caches dependencies to speed up future builds.
+4. Deploys the site to GitHub Pages using mkdocs `gh-deploy`.
+
+This workflow ensures the documentation is always up to date and available on GitHub Pages whenever changes are made to relevant Markdown files or the MkDocs configuration.

mkdocs/docs/developer/mkdocs-edit-instructions.md

@@ -0,0 +1,38 @@
+# How to Edit MkDocs
+
+To make changes to the docs, you have to edit the `.md` files located in the `mkdocs/docs/` folder. To make a new page, you have to create a new `.md` file in the appropriate folder.
+
+MkDocs provides a development server that makes it convenient to see your changes in `localhost` before you deploy them to github.
+
+### Quickstart
+
+To start the development server, simply go to the root of your project in the terminal and run the following command:
+
+```bash
+docker-compose -f docker-compose.docs.yml up --watch
+```
+
+Next, go to `http://localhost:8005` in your browser.
+
+Now when you save new changes to the `.md` files, the respective page will automatically be updated in the browser.
+
+When you are done editing, the next step is to deploy your changes.
+
+### Deploying your changes
+
+When you are satisfied with your edits, make a pull request so that they can be reviewed.
+
+Once the pull request is approved and merged into `develop`, the changes will be automatically deployed to the official CivicTechJobs documentation site (the site you are reading this page in right now). That's it!
+
+If anything goes wrong, you can investigate the workflow in the project's [github actions page](https://github.com/hackforla/CivicTechJobs/actions)
+
+**Note**: At the moment, the docs are set to deploy from the `develop` branch, using the github action located in `mkdocs-build.yml`. This means that whenever a file is changed inside the `mkdocs/` directory, and is merged into the `develop` branch on github, the changes will be automatically deployed to the official site hosted on github pages. In the near future we will set it to deploy from the `main` branch.
+
+### Recap
+
+To sum it all up, you can make changes in 4 easy steps:
+
+1. Start the development server using `docker-compose -f docker-compose.docs.yml up --watch`
+2. Make changes to the `.md` files and observe them in `http://localhost:8005`
+3. Open a Pull Request with your new changes
+4. Merge the Pull Request into the `develop` branch

mkdocs/docs/developer/mkdocs.md

@@ -0,0 +1,45 @@
+# MkDocs guide
+
+We are using mkdocs to handle documentation.
+
+Developers should document their architectural and coding decisions in here, so that other team members can easily reference these docs whenever they are lost or confused or new to the project.
+
+### What is MKdocs?
+
+[MkDocs](https://www.mkdocs.org/) is a static site generator that is designed specifically for building project documentation. It allows you to write documentation using [Markdown](https://www.markdownguide.org/), a lightweight markup language that's easy to use, and generates a clean, professional website that can be hosted on our project's GitHub Pages.
+
+### What should developers document?
+
+Code functionality
+
+- Document the purpose and functionality of the code you write. Describe what each module, class, or function does, especially if it might not be obvious at first glance.
+- Example: If you implement a new API endpoint, document what the endpoint does, the request and response formats, and any important business logic involved.
+
+Setup Instructions
+
+- Make sure to document how to set up the project or new features you add. Include all dependencies, environment variables, and steps to get the project running locally or in production.
+- Example: If you introduce a new tool like Docker or a new package, make sure to document how to install and configure it.
+
+Common Use Cases
+
+- Document common or important use cases for the code. This is especially useful for other developers who might use your code in the future.
+- Example: If you build a new utility or library, include examples showing how it should be used.
+
+Troubleshooting
+
+- Include a section for common issues and how to resolve them. This can be a lifesaver for both new developers and anyone maintaining the project.
+- Example: Document errors or challenges you faced during development and their solutions.
+
+Code Examples
+
+- Where applicable, provide sample code or snippets to explain usage. These examples help future developers quickly understand how to use your components or functions.
+- Example: If you write a custom hook in React, include an example of how it can be used in a component.
+
+API Documentation
+
+- Ensure that all APIs (REST or GraphQL) have detailed documentation on endpoints, parameters, return types, and possible error codes.
+- Example: For each API endpoint, include descriptions of what it does, what data it expects, and the structure of its responses.
+
+### What are best practices for documentation?
+
+Keep it updated and consistent. Be clear and concise. Write in simple terms. Use examples.

docs/joining-the-team/web-developer.md → mkdocs/docs/joining-the-team/web-developer.md

@@ -10,7 +10,7 @@
 
 1. Communicate with the PM about your interest in being assigned a task.
 
-1. Your first commit will likely be an issue labeled good first issue. Check [the board](https://github.com/hackforla/[INSERT-REPO-NAME-HERE]/projects/1?card_filter_query=label%3A%22good+first+issue%22) for those issues. Don't worry if you don't see anything now, we are working on it.
+1. Your first commit will likely be an issue labeled good first issue. Check [the board](https://github.com/hackforla/CivicTechJobs/projects/37) for those issues. Don't worry if you don't see anything now, we are working on it.
 
 ## Additional Reading
 

mkdocs.yml → mkdocs/mkdocs.yml

@@ -29,6 +29,9 @@ nav:
           - Frontend Architecture: developer/frontend.md
           - GitHub Architecture: developer/github.md
           - Installation Instructions: developer/installation.md
+          - MkDocs Architecture: developer/mkdocs-architecture.md
+          - MkDocs Guide: developer/mkdocs.md
+          - MkDocs - How to Edit: developer/mkdocs-edit-instructions.md
       - Misc:
           - ADA Guide: misc/ada-guide.md
           - Glossary: misc/glossary.md