Introduce TypeDoc and Improve Documentation for New Contributors

thompsondt commented 2 weeks ago

Overview

This pull request introduces TypeDoc for generating documentation directly from the project source code. It also enhances the documentation to help new contributors understand the project structure and components. The updated documentation includes detailed descriptions of Page components, App and Document overrides, reusable React components, and the key overpassQuery function.

Related Issues

(NONE)

Details

TypeDoc Integration: Added TypeDoc to the project for automated documentation generation from source code comments.
Page Components: Documented the structure and composition of Page components, detailing how they are composed of subcomponents.
App and Document Overrides: Added documentation for the custom overrides to the App and Document components in the Next.js project.
Reusable React Components: Provided detailed descriptions of the reusable React components used across the project.
Key Function Documentation: Added lightweight documentation for the overpassQuery function that handles pulling geospatial information from OpenStreetMap.
Project Structure: Added some starter notes detailing the project structure, including only essential files and folders for comprehending the project.

Checklist

[x] Documentation is clear and comprehensive.
- [x] Includes a project structure overview (essentials)
- [x] Adds page component descriptions
- [x] Documents reusable react components
[x] TypeDoc is correctly integrated and generates the expected documentation.

vercel[bot] commented 2 weeks ago

@thompsondt is attempting to deploy a commit to the ClashTips Team on Vercel.

A member of the Team first needs to authorize it.

CurtisGreen commented 2 weeks ago

@thompsondt

I get this error when trying to generate the docs, there's probably something you have installed locally that needs to be added to the dev dependencies

npm install
npm run docs
> sidewalk-app@0.1.0 docs
> typedoc

[info] Loaded plugin typedoc-plugin-merge-modules
src/components/Window.tsx:3:33 - error TS7016: Could not find a declaration file for module '@heroicons/react/20/solid'. 'C:/Users/Curtis/Documents/github/opensidewalkmap-fork/opensidewalkmap/node_modules/@heroicons/react/20/solid/index.js' implicitly has an 'any' type.

3 import { ChevronDownIcon } from "@heroicons/react/20/solid";
                                  ~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/components/Window.tsx:4:39 - error TS7016: Could not find a declaration file for module '@heroicons/react/24/outline'. 'C:/Users/Curtis/Documents/github/opensidewalkmap-fork/opensidewalkmap/node_modules/@heroicons/react/24/outline/index.js' implicitly has an 'any' type.

4 import { InformationCircleIcon } from "@heroicons/react/24/outline";
                                        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/components/ZoomModal.tsx:3:41 - error TS7016: Could not find a declaration file for module '@heroicons/react/24/outline'. 'C:/Users/Curtis/Documents/github/opensidewalkmap-fork/opensidewalkmap/node_modules/@heroicons/react/24/outline/index.js' implicitly has an 'any' type.

3 import { ExclamationTriangleIcon } from "@heroicons/react/24/outline";
                                          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

thompsondt commented 2 weeks ago

Hmm... that is interesting. I do see the two new dev dependencies in the commit. I'll try to replicate this error in a clean environment.

thompsondt commented 2 weeks ago

It was more for my benefit in gaining a comprehensive understanding the project. I looked for other solutions, but couldn’t find anything that didn’t decouple the docs from the code. I’m okay with holding onto my project notes privately if the pull adds complexity without value.

On Sun, Jun 30, 2024 at 11:24 AM CurtisGreen @.***> wrote:

@.**** commented on this pull request.

In src/components/CheckBox.tsx https://github.com/CurtisGreen/opensidewalkmap/pull/8#discussion_r1660201726 :

@@ -1,5 +1,9 @@ import React, { Dispatch, ReactNode, SetStateAction } from "react";

+/**

Renders a checkbox

@group Components

Have you used typedoc with react before? If it’s not meant for it I’m wondering if it’s worth doing versus adding more comments / refactoring the code.

I’m not saying this won’t work or I won’t approve it, but I just want to make sure this is thought out and beneficial

— Reply to this email directly, view it on GitHub https://github.com/CurtisGreen/opensidewalkmap/pull/8#discussion_r1660201726, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAL6IE3OAUQSDL74IFXJ5PDZKAPMVAVCNFSM6AAAAABKCTDSQ6VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDCNJQGA3TCOJWGQ . You are receiving this because you were mentioned.Message ID: @.***>

CurtisGreen commented 2 weeks ago

Hmm... that is interesting. I do see the two new dev dependencies in the commit. I'll try to replicate this error in a clean environment.

I deleted and reinstalled it and it worked the 2nd time, not sure what was wrong 🤔

thompsondt commented 2 weeks ago

@CurtisGreen I appreciate that you want to give me the flexibility to pick here and I appreciate your feedback during the review. I want to acknowledge your concerns about the docs I'm introducing and how their integration doesn't quite sit right with either of us.

May be it's inappropriate to tie the docs closely to the code at the application level. TypeDoc gets unwieldy trying to apply it in this way. The updated markdown notes document the project structure at a high level, and that's probably enough for those already familiar with Next.js.

Here's what I propose:

Remove the TypeDoc documentation and new dev dependencies -- reducing complexity
Keep the markdown notes and add details when we make structural changes -- facilitating clarity and communication

I feel confident this is enough to help would-be contributors and enough for myself as I studied the code closely.

CurtisGreen / opensidewalkmap