From 6b2c0791b9ac8b0f4f41cec58103ecce2ff18242 Mon Sep 17 00:00:00 2001 From: Terence Lo Date: Tue, 8 Oct 2024 15:51:03 -0700 Subject: [PATCH] update mkdocs --- mkdocs/docs/developer/backend.md | 2 ++ mkdocs/docs/developer/frontend.md | 2 ++ mkdocs/docs/developer/mkdocs-architecture.md | 2 ++ .../docs/developer/mkdocs-edit-instructions.md | 18 ++++++++++++++++-- .../developer/{mkdocs.md => mkdocs-guide.md} | 11 ++++++++--- mkdocs/docs/resources.md | 5 +++++ mkdocs/mkdocs.yml | 2 +- 7 files changed, 36 insertions(+), 6 deletions(-) rename mkdocs/docs/developer/{mkdocs.md => mkdocs-guide.md} (83%) diff --git a/mkdocs/docs/developer/backend.md b/mkdocs/docs/developer/backend.md index 5c352361..dd674b64 100644 --- a/mkdocs/docs/developer/backend.md +++ b/mkdocs/docs/developer/backend.md @@ -44,6 +44,8 @@ _

Overall project structure

_ _

Backend Architecture

_ +These diagrams show how data flows through the app: [Frontend and Backend UML diagrams](https://github.com/hackforla/CivicTechJobs/issues/236) + ## Summary **Backend Tech Stack**: Django, DjangoRESTFramework diff --git a/mkdocs/docs/developer/frontend.md b/mkdocs/docs/developer/frontend.md index 73e832da..2ed7a476 100644 --- a/mkdocs/docs/developer/frontend.md +++ b/mkdocs/docs/developer/frontend.md @@ -57,6 +57,8 @@ _

Overall project structure

_ _

Frontend Architecture

_ +These diagrams show how data flows through the app: [Frontend and Backend UML diagrams](https://github.com/hackforla/CivicTechJobs/issues/236) + ## Summary **Frontend Tech Stack**: React, Babel, webpack, Jest, React Testing Library, HTML, SCSS, JS, TailwindCSS diff --git a/mkdocs/docs/developer/mkdocs-architecture.md b/mkdocs/docs/developer/mkdocs-architecture.md index 9e454905..1b74edab 100644 --- a/mkdocs/docs/developer/mkdocs-architecture.md +++ b/mkdocs/docs/developer/mkdocs-architecture.md @@ -101,6 +101,8 @@ The docs are set to automatically deploy to github pages using the `mkdocs-build ### Github Action for mkdocs deployment +Links to the github action: [Build MkDocs site (develop)](https://github.com/hackforla/CivicTechJobs/actions/workflows/mkdocs-build.yml) + ```yml name: Build MkDocs site (develop) diff --git a/mkdocs/docs/developer/mkdocs-edit-instructions.md b/mkdocs/docs/developer/mkdocs-edit-instructions.md index beea45c6..d54f9f75 100644 --- a/mkdocs/docs/developer/mkdocs-edit-instructions.md +++ b/mkdocs/docs/developer/mkdocs-edit-instructions.md @@ -1,9 +1,21 @@ -# How to Edit MkDocs +# How to Publish new Documentation -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. +The goal of this page is to document how to create and publish new changes to the CTJ documentation. + +Writing documentation into mkdocs requires some knowledge of [Markdown](https://www.markdownguide.org/). + +### Making changes to the mkdocs + +What you essentially need to know: + +- To make changes to the docs, edit the `.md` files located in the `mkdocs/docs/` folder. +- To make a new page, create a new `.md` file in the appropriate folder. +- To add or edit links in the navmenu, configure the `mkdocs.yml` file. MkDocs provides a development server that makes it convenient to see your changes in `localhost` before you deploy them to github. +*For more a detailed editing guide please see the official [MkDocs Tutorial](https://www.mkdocs.org/getting-started/)* + ### Quickstart To start the development server, simply go to the root of your project in the terminal and run the following command: @@ -28,6 +40,8 @@ If anything goes wrong, you can investigate the workflow in the project's [githu **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. +*Check out our [MkDocs Architecture](mkdocs-architecture.md) page for more details on how it all fits together.* + ### Recap To sum it all up, you can make changes in 4 easy steps: diff --git a/mkdocs/docs/developer/mkdocs.md b/mkdocs/docs/developer/mkdocs-guide.md similarity index 83% rename from mkdocs/docs/developer/mkdocs.md rename to mkdocs/docs/developer/mkdocs-guide.md index 724d3336..8922cbec 100644 --- a/mkdocs/docs/developer/mkdocs.md +++ b/mkdocs/docs/developer/mkdocs-guide.md @@ -1,13 +1,15 @@ -# MkDocs guide +# MkDocs - Documentation 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. +Developers should document their architectural and coding decisions, 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. +Please see [MkDocs - How to Edit](mkdocs-edit-instructions.md) for instructions on how to make changes to the CTJ documentation and publish new docs. + ### What should developers document? Code functionality @@ -42,4 +44,7 @@ API Documentation ### What are best practices for documentation? -Keep it updated and consistent. Be clear and concise. Write in simple terms. Use examples. +- Keep it updated and consistent. +- Be clear and concise. +- Write in simple terms. +- Use examples. diff --git a/mkdocs/docs/resources.md b/mkdocs/docs/resources.md index d57cd306..775625e2 100644 --- a/mkdocs/docs/resources.md +++ b/mkdocs/docs/resources.md @@ -19,6 +19,7 @@ More resources to be added as project progresses: 2. [Project one sheet](https://docs.google.com/document/d/1bfxY8YlyCjzCL3oP0rpa77uEY4vuymDYZY_xWEgXiGs) 3. [Our Shared Google Drive](https://drive.google.com/drive/folders/1hXxvpC8W5Uuzjqo4CxnjDpAMI7sbVnq8?usp=sharing&pli=1) 4. [GitHub Workflow](https://docs.google.com/document/d/1CuRX6hhWzs8ydVCnl6OrGZ4LeVSk9X_pIzoKchAqFcU) +5. [Milestones](https://github.com/hackforla/CivicTechJobs/milestones) ### Roadmaps @@ -41,6 +42,10 @@ More resources to be added as project progresses: 4. [Task and User Flow](https://whimsical.com/ctj-task-and-user-flow-8GgB5Moy14fnQDv24o1fGC) 5. [HfLA Website Figma - Section for Volunteer Opportunities](https://www.figma.com/design/0RRPy1Ph7HafI3qOITg0Mr/Hack-for-LA-Website?node-id=5326-26395&t=x2ib7NJm3z5aB5H0-0) +### Diagrams + +1. [Frontend and Backend UML diagrams](https://github.com/hackforla/CivicTechJobs/issues/236) + ### For Developers 1. [Contributing.md](https://github.com/hackforla/CivicTechJobs/blob/main/CONTRIBUTING.md)
diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index 39ea4dc0..9706fe83 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -30,7 +30,7 @@ nav: - GitHub Architecture: developer/github.md - Installation Instructions: developer/installation.md - MkDocs Architecture: developer/mkdocs-architecture.md - - MkDocs Guide: developer/mkdocs.md + - MkDocs - Documentation Guide: developer/mkdocs-guide.md - MkDocs - How to Edit: developer/mkdocs-edit-instructions.md - Misc: - ADA Guide: misc/ada-guide.md