First pass at docs (#355)

outofambit · web-flow · commit b368edc8ed3d · 2024-05-16T23:49:57.000Z
* add basic technical overview

* reorder npm tasks

* Create localization.md

* Create styles_architecture.md

* Create scripts.md

* remove dead npm scripts

* update script names

* create docs folder
diff --git a/README.md b/README.md
@@ -1,7 +1,15 @@
-# WIP
+# [BETA] p5.js Website
 
-This project is undergoing **major changes** currently. This will be the case until the end of April. If you are here to edit or translate content, please do so inside [the `src/content/` folder](https://github.com/bocoup/p5.js-website/tree/main/src/content)
+## Contributing
 
-## Adding Libraries
+### Content Changes
 
-Follow the steps in the <a href="./contributing_libraries.md">Contributing Libraries</a> doc if you would like to add your libary to the collection!
+If you are here to edit or translate content, please do so inside [the `src/content/` folder](/src/content).
+
+### Code Changes
+
+For making code changes, check out the [technical overview](./docs/techical-overview.md) to get started.
+
+### Adding Libraries
+
+Follow the steps in the <a href="./docs/contributing_libraries.md">Contributing Libraries</a> doc if you would like to add your libary to the collection!
diff --git a/contributing_libraries.md b/contributing_libraries.md
diff --git a/docs/contributing_libraries.md b/docs/contributing_libraries.md
@@ -0,0 +1,24 @@
+# p5.js Libraries
+
+p5.js welcomes libraries contributed by others! <a href="https://github.com/processing/p5.js/blob/main/contributor_docs/creating_libraries.md">Check out the libraries tutorial</a> for more specifics about how to create one. If you have created a library and would like to have it included in the list, follow the instructions below!
+
+1. Fork the repo
+2. Add a file to the <a href="/src/content/libraries/en/">`src/content/libraries/en`</a> folder named `yourLibraryName.yaml` (or consider <a href="src/content/libraries/en/p5.warp.yaml">copying an existing library</a> as a starting point)
+3. Inside it, add the following content:
+   - `name`: The name of the library
+   - `category`: A category that you think best fits your library. Your choices include: `drawing`, `color`, `ui`, `math`, `physics`, `algorithms`, `3d`, `ai-ml-cv`, `animation`, `shaders`, `language`, `hardware`, `sound`, `data`, `teaching`, `networking`, `export`, or `utils`.
+   - `description`: A one-sentence description of the library
+   - `author`: An object containing `name`, your name, and `url`, an optional link to your website. If there are multiple authors, use an array of author objects.
+   - `sourceUrl`: A link to the library's source code (e.g. its repo on GitHub or GitLab)
+   - (Optional) `websiteUrl`: A link to a website for the library
+   - (Optional) `npm`: If applicable, the package name for the library on <a href="https://www.npmjs.com/">npm</a>
+   - (Optional) `npmFilePath`: A path like `'dist/library.min.js'` if a specific file in the library should be used from npm. You can test this out by going to `https://cdn.jsdelivr.net/npm/packageName` -- if that doesn't work, try `https://cdn.jsdelivr.net/npm/packageName/path/to/file.js` and put the path you added into this property
+   - `featuredImage`: The relative path to the preview thumbnail for the library.
+   - `featuredImageAlt`: a short description of the contents of the thumbnail for screen readers
+   - (Optional) `license`: A <a href="https://docs.npmjs.com/cli/v10/configuring-npm/package-json#license">string describing the software license of the library.</a> This may be omitted if your package is on npm and has license info there
+4. Add a **high-res colored image of 1500x1000px** of your library into `src/content/libraries/images`
+5. Submit a pull request and we'll review your submission
+
+We add libraries that are open-source, includes some documentation and examples, and <a href="https://github.com/processing/p5.js/blob/main/CODE_OF_CONDUCT.md">follow our code of conduct.</a> This directory targets beginner users, so we aim to ensure users have a smooth experience getting started with any library linked to.
+
+If you have any questions, feel free to open an issue or create a work-in-progress PR and ask us anything!
diff --git a/docs/localization.md b/docs/localization.md
@@ -0,0 +1,34 @@
+# Localization Architecture
+
+An important feature of the p5.js website is support multiple languages (four and counting!). This requires the website to build and serve every page in each of the supported languages.
+
+Our website framework Astro has localization support, but it doesn't cover our full set of needs so the localization tooling in this repo is largely [hand rolled](https://www.quora.com/Computer-Science-Where-did-the-phrase-Roll-your-own-come-from-and-why-is-it-used-in-CS).
+
+## Supported Languages and Language Codes
+
+The languages that will be built and included in the language dropdown menu are defined in [`/src/i18n/const.ts`](/src/i18n/const.ts) The language codes used in that list define both the routes for localized content (for example: the "es" in https://p5js.org/es/examples) as well as the expected language folders in each content collection (every folder in [`/src/content`](/src/content)). These generally follow [these language codes](https://en.wikipedia.org/wiki/ISO_639-1).
+
+## Translation Authoring Locations
+
+Almost all strings and text are stored within content collections in src/content.
+
+Every content collection in `src/content` is divided into language-specific folders. The pages in a collection must have the same name in each language folder.
+
+Each file within these collection folders corresponds to a real page on the rendered website.
+
+The ["ui" content collection](src/content/ui/) is a little different than the others. It contains yaml files that cover strings that are used across different pages for things like the navigation bar.
+
+## Routes and Layouts
+
+Astro uses a file-based approach to generating routes. The filepath of each file in `src/pages` becomes the url of the page it renders. Because we need to support a url scheme where English translations of pages are served at a URL with no locale prefix (for example, the English version of the tutorials page is at https://p5.js/tutorials _not_ https://p5.js/en/tutorials), there are 2 sets of routing files and folders: one in `src/pages` and another `src/pages/[locale]`. The `[locale]` set are needed to build and serve the non-English pages (whose URLs are also prefixed by the language codes).
+
+Taking the tutorials page as an example:
+
+- `src/pages/tutorials` is the route for the English tutorials page
+- `src/pages/[locale]/tutorials` is the route for all other translations of the tutorials page
+
+Both of these routes use the [TutorialsLayout](/src/layouts/TutorialsLayout.astro) to render the page by passing in the content in the correct language.
+
+The main difference between these two routing files is how they retrieve the correct translation. The English version retreives the English version of the content. The other translations retrieve their version of the content and then fill in any gaps with English versions. See `getCollectionInLocaleWithFallbacks()` for how this works.
+
+Because of this subtle duplication, we try to keep the files in `src/pages/` as short as possible and move rendering logic into the [layout files](/src/layouts/).
diff --git a/docs/scripts.md b/docs/scripts.md
@@ -0,0 +1,21 @@
+# Scripts
+
+This repo includes a few scripts to pull content from external sources, primarily the [p5.js repo](https://github.com/processing/p5.js).
+
+They are all runnable via npm scripts.
+
+## Search Indices Build Script
+
+`npm run build:search` generates metadata about the content of the website so the search functionality can show relevant results.
+
+## Contributor Docs Build Script
+
+`npm run build:contributor-docs` copies the contributor docs from the p5.js website repo and places them into the [contributor docs content collection](/src/content/contributor-docs).
+
+## Reference Build Script
+
+`npm run build:reference` parses the inline documentation in the p5.js source code (the JSDoc comments) and generates the pages in the [reference collection](/src/content/reference). Because the directly inline documentation for p5.js is only in English, this script will only update the English translation of the reference.
+
+## Contributors List Build Script
+
+`npm run build:contribtuors` parses the list of contributors from the all contributors [config file](https://github.com/processing/p5.js/blob/main/.all-contributorsrc) in the p5.js repo and adds entries in the [people collection](src/content/people/en) for anyone who is missing. These are used to render the list of contributors on the [People page](https://p5js.org/people/). This script will **not** remove or update existing entries, that must be done manually.
diff --git a/docs/styles_architecture.md b/docs/styles_architecture.md
@@ -0,0 +1,40 @@
+# Styling (CSS) Architecture
+
+## Methods
+
+There are a few ways you can write CSS in this project:
+
+### 1. Use [Tailwind](https://tailwindcss.com/) css classes directly within layouts and components
+
+This is often the fastest way to add custom styles if you are familair with [Tailwind](https://tailwindcss.com/). See a good example in `/src/p5/p5.js-website/src/components/Footer/index.astro`.
+
+### 2. Write styles in the [SCSS](https://sass-lang.com/) files in `/styles` and use those classes in layouts and components
+
+The styles folder is primarily meant for foundational styles that are used across pages and components. The majority of it is in `/styles/global.scss`.
+
+### 3. Write a `styles.module.scss` file for a specific component and import it into that component
+
+This can be useful for situations where the styling you need for a particular area is very complex and hard to distill in simple Tailwind classes. See a good example of this approach in `/src/components/Dropdown`.
+
+#### 4. Write css in a style tag within an `.astro` file
+
+This can be a good approach when you need a few custom styles for a single a layout or component but adding an extra SCSS feels like overkill. See an example in `/src/layouts/AboutLayout.astro`
+
+## Useful Global Styles
+
+These global classes may do exactly what you need:
+
+### Grids
+
+Both of these are useful for laying out a series of items in a responsive grid with the right spacing.
+
+- .content-grid
+- .content-grid-simple
+
+### Sections
+
+Page layouts rely on having content within one or more `<section>`'s (or `.section`'s) to have proper spacing.
+
+### Markdown
+
+The `.rendered-markdown` class is intended to wrap areas where we render markdown content from a content collection. See `/src/layouts/TextDetailLayout.astro` for a simple example.
diff --git a/docs/technical_overview.md b/docs/technical_overview.md
@@ -0,0 +1,68 @@
+# Technical Overview
+
+## Getting Started with Development
+
+### Setup
+
+1. Make sure you have [node and npm installed on your machine](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs).
+2. Clone this repo by typing git clone https://github.com/processing/p5.js-website/ in your terminal. (You can also use [GitHub Desktop](https://desktop.github.com/)).
+3. Then install the project's dependencies with:
+
+```shellsession
+npm install
+```
+
+### Running
+
+Running this will start up a local dev server and print out the address in your terminal (for example: http://localhost:4321/). Open that page in your browser to see the website.
+
+```shellsession
+npm run dev
+```
+
+## File Organization
+
+The website code is divided into a few main folders:
+
+- `src/content/` this is where almost all content authoring happens in the repo. These files contain the content that is used to generate the website.
+- `src/components/` holds UI elements that are rendered on different pages of the website. Things like basic buttons, as well as more specialized things like the top navigation menus are here.
+- `src/layouts/` this contains the basic visual structure of each page. If you are looking to edit a specific page of the website, finding the layout for it in this folder is a great place to start.
+- `src/pages/` these files are primarily used to create the routes (the different URLs) for the pages of the website and pull content from `src/content/`. Note that every route basically exists twice: once in `src/pages/` and again in `src/[locale]/pages/` to support localized urls. Read more about this in [./localization-architecture.md]
+- `src/scripts/` contains utility scripts that update the files in `src/content/` with changes in the p5.js repo
+- `styles/` contains globally applied css styles for the website
+- `test/` contains a set of unit tests that cover some important utility functions and key components
+
+## Making Changes
+
+As you make changes to the code on the site, the page you see rendered in the browser from `npm run dev` will update automatically. However, you may need to refresh to see some styling changes reflected.
+
+You can check your work with the following commands. These will run type checking on typescript files and check for common mistakes in javascript files.
+
+```shellsession
+npm run lint
+npm run check
+```
+
+## Running Tests
+
+To run the suite of unit tests, use:
+
+```shellsession
+npm run test
+```
+
+## Building the site
+
+We are using the [Astro framework](https://astro.build) as a [static site generator](https://docs.astro.build/en/basics/rendering-modes/#pre-rendered), which means that the build process renders every single page of the website as HTML (and JavaScript and CSS) and then serves them using a simple server. These are then uploaded to [GitHub Pages](https://pages.github.com/). This all happens automatically with GitHub Actions when code is merged to the `main` branch in this repo.
+
+You can try building the site locally with
+
+```shellsession
+npm run build
+```
+
+And then view it locally with
+
+```shellsession
+npm run preview
+```
diff --git a/package.json b/package.json
@@ -10,13 +10,11 @@
     "build": "astro check && astro build",
     "preview": "astro preview",
     "astro": "astro",
-    "build:contribute": "tsx ./src/scripts/builders/contribute.ts",
-    "build:reference": "tsx ./src/scripts/builders/reference.ts",
-    "build:search": "tsx ./src/scripts/builders/search.ts",
-    "build:people": "tsx ./src/scripts/builders/people.ts",
     "test": "vitest",
-    "build:examples": "node ./src/scripts/build-examples.js",
-    "postprocess:links": "tsx ./src/scripts/postprocess-locale-relative-links.ts"
+    "build:contributor-docs": "tsx ./src/scripts/builders/contribute.ts",
+    "build:contributors": "tsx ./src/scripts/builders/people.ts",
+    "build:reference": "tsx ./src/scripts/builders/reference.ts",
+    "build:search": "tsx ./src/scripts/builders/search.ts"
   },
   "dependencies": {
     "@astrojs/check": "^0.5.5",
