chore: Add initial documentation to Docusaurus site #897

cmumatt · 2022-02-28T15:48:46Z

Description

This PR updates the TypeDoc dependency, adds the TypeDoc Markdown plugin, and begins to fill out the documentation on the Docusaurus site. It also removes the empty Blog and adds a team page, currently without headshots.

Due to poor results auto-generating Markdown docs from TypeDoc function dictionaries, this PR does not include an automated pipeline for function doc generation. This and language documentation will be addressed in subsequent PRs.

Implementation strategy and design decisions

Load initial documentation into Docusaurus site.

Checklist

I have commented my code, particularly in hard-to-understand areas
My changes generate no new ESLint warnings
I have reviewed any generated changes to the diagrams/ folder

Open questions

Auto-generate function documentation, possibly using the JSON output from TypeDoc
Add language documentation

codecov · 2022-02-28T15:54:04Z

Codecov Report

Merging #897 (e577d4b) into main (cf8cf79) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #897   +/-   ##
=======================================
  Coverage   67.79%   67.79%           
=======================================
  Files          62       62           
  Lines        8120     8120           
  Branches     1769     1769           
=======================================
  Hits         5505     5505           
  Misses       2608     2608           
  Partials        7        7

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ce0a2da...e577d4b. Read the comment docs.

cloudflare-pages · 2022-02-28T16:01:51Z

Deploying with Cloudflare Pages

Latest commit:	`e577d4b`
Status:	✅ Deploy successful!
Preview URL:	https://2b256015.penrose-panes.pages.dev

View logs

maxkrieger · 2022-02-28T19:34:13Z

@cmumatt have you seen https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/docusaurus-plugin-typedoc ? Not sure how well it works 😄

for future reference heres some other resources in my browser history when I was trying to autogenerate .md files for docusaurus. I was trying to make a plugin, the skeleton of which is in penrose-data plugin. Unfortunately I forgot what got me stuck:

Extend existing doc plugin? graphql-markdown/graphql-markdown#144 (comment) ❗
Allow routes generated by addRoute to be listed in the plugin-content-docs sidebar facebook/docusaurus#6067 (comment)
Extend existing content plugins (CMS integration, middleware, doc gen...) facebook/docusaurus#4138 (comment)
Add ability to autogenerate docs md files from sidebar definition facebook/docusaurus#2787

samestep

Looks awesome, thanks so much for writing this up @cmumatt!

I wrote a few comments/suggestions (mostly just typo corrections).

samestep · 2022-03-01T15:00:06Z

packages/docs-site/.gitignore

+!Style
+!Substance


Could you clarify what exactly these are referring to? I don't see any files or folders in this PR whose name is Style or Substance (with a leading capital S).

packages/docs-site/docs/tutorial/basics.md

samestep · 2022-03-01T15:05:19Z

packages/docs-site/docs/tutorial/basics.md

@@ -85,9 +85,9 @@ forall Set x {
 }
 ```

-So, what are the shapes we can use? Currently, the system supports 12 different shapes, and you can find the specs for every shape [here](/docs/api/). It is a page that you will visit frequently as you work in Penrose.
+So, what are the shapes we can use? Currently, the system supports 12 different shapes, and you can find the specs for every shape [here](/docs/ref/). It is a page that you will visit frequently as you work in Penrose.


Is it possible to create a parent page for "Shape Library", and link to that? Currently this just links to the root documentation page, and if someone doesn't already have "Style" expanded in the sidebar, it's unclear where they're supposed to go from here.

samestep · 2022-03-01T15:05:33Z

packages/docs-site/docs/tutorial/basics.md

@@ -113,7 +113,7 @@ Now it's time to see all of our hard work (drumroll please 🥁)! To compile you

 ## Exercise

-We have now covered the differences between and usage of the `.dsl`, `.sub` and `sty` files. We have provided 3 exercises for you to help solidify the basics. You can work on each of these within the existing files - no need to make new ones. **Hint:** Make use of the shape specs [here](/docs/api/).
+We have now covered the differences between and usage of the `.dsl`, `.sub` and `sty` files. We have provided 3 exercises for you to help solidify the basics. You can work on each of these within the existing files - no need to make new ones. **Hint:** Make use of the shape specs [here](/docs/ref/).


Same question here.

samestep · 2022-03-01T15:05:40Z

packages/docs-site/docs/tutorial/basics.md

@@ -129,7 +129,7 @@ _Since we are not defining all the properties that control how the shape will lo

 ![](/img/tutorial/tutorial1c3.png)

- **Challenge 4:** Keep 3 sets. For each set, represent `Set` as both a `Circle` and a square. There should be 6 objects on your canvas. (Hint: you will need to initialize another [Shape](/docs/api/) object!)
+- **Challenge 4:** Keep 3 sets. For each set, represent `Set` as both a `Circle` and a square. There should be 6 objects on your canvas. (Hint: you will need to initialize another [Shape](/docs/ref/) object!)


samestep · 2022-03-01T15:06:16Z

packages/docs-site/src/components/_ShapeProps.js

@@ -1,5 +1,6 @@
 import { makeCanvas, shapedefs } from "@penrose/core";
 import React from "react";
+import seedrandom from "seedrandom";


Thanks for fixing this! Weird that it didn't already show up in CI or something?

packages/docs-site/docs/ref/index.mdx

packages/docs-site/docs/ref/style/index.mdx

cmumatt · 2022-03-01T18:13:03Z

@cmumatt have you seen https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/docusaurus-plugin-typedoc ? Not sure how well it works 😄

Yes, that is a good one!

That plugin is what generated the MD output for the functions. Unfortunately, the output is not useful just for function dictionaries; hence, the manual transformation step. The plan is to eliminate that step and automate the flow in a future PR. Appreciate the other links -- I will look through them, too!

Co-authored-by: Sam Estep <sam@samestep.com>

cmumatt added 10 commits February 7, 2022 19:51

Initial checkin

6650e44

Upgrade TypeDoc + Markdown, ongoing doc work

e7fa8b6

Further documentation updates

5baaf0e

Further documentation updates

ee3aa91

Further documentation updates

01b80f7

Further documentation updates

2dda415

Renamed tutorial link & added Brad to team page

cae72c8

Merge remote-tracking branch 'origin/main' into doc-update

17055ad

Delete headshots (for now)

3a47971

Removed broken auto-generated links

d9b7a9e

Update TypeDoc HTML output path

4fd5e20

Prettier for sidebar.js

b218155

cmumatt changed the title ~~Add initial documentation to Docusaurus site~~ chore: Add initial documentation to Docusaurus site Feb 28, 2022

cmumatt marked this pull request as ready for review February 28, 2022 16:11

cmumatt requested review from samestep and wodeni February 28, 2022 16:12

samestep approved these changes Mar 1, 2022

View reviewed changes

samestep mentioned this pull request Mar 1, 2022

chore: Add MDX extension to penrose.code-workspace #899

Merged

cmumatt and others added 7 commits March 1, 2022 13:15

Update packages/docs-site/docs/ref/index.mdx

8de0bba

Co-authored-by: Sam Estep <sam@samestep.com>

Update packages/docs-site/docs/ref/index.mdx

f889ad8

Co-authored-by: Sam Estep <sam@samestep.com>

Update packages/docs-site/docs/tutorial/basics.md

d3eeb01

Co-authored-by: Sam Estep <sam@samestep.com>

Update packages/docs-site/docs/ref/index.mdx

9dbde97

Co-authored-by: Sam Estep <sam@samestep.com>

Update packages/docs-site/docs/ref/style/index.mdx

a7dac40

Co-authored-by: Sam Estep <sam@samestep.com>

Merge branch 'main' into doc-update

985c208

Run Prettier

e577d4b

cmumatt merged commit 33c882d into main Mar 2, 2022

cmumatt deleted the doc-update branch March 2, 2022 20:39

samestep mentioned this pull request Mar 3, 2022

Make Tutorial hyperlinks into the reference doc site more specific #902

Open

wodeni mentioned this pull request May 25, 2023

docs: auto-generate documentation for Style functions #1427

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: Add initial documentation to Docusaurus site #897

chore: Add initial documentation to Docusaurus site #897

cmumatt commented Feb 28, 2022 •

edited

codecov bot commented Feb 28, 2022 •

edited

cloudflare-pages bot commented Feb 28, 2022 •

edited

maxkrieger commented Feb 28, 2022 •

edited

samestep left a comment

samestep Mar 1, 2022

samestep Mar 1, 2022

samestep Mar 1, 2022

samestep Mar 1, 2022

samestep Mar 1, 2022

cmumatt commented Mar 1, 2022

		!Style
		!Substance

chore: Add initial documentation to Docusaurus site #897

chore: Add initial documentation to Docusaurus site #897

Conversation

cmumatt commented Feb 28, 2022 • edited

Description

Implementation strategy and design decisions

Checklist

Open questions

codecov bot commented Feb 28, 2022 • edited

Codecov Report

cloudflare-pages bot commented Feb 28, 2022 • edited

Deploying with Cloudflare Pages

maxkrieger commented Feb 28, 2022 • edited

samestep left a comment

Choose a reason for hiding this comment

samestep Mar 1, 2022

Choose a reason for hiding this comment

samestep Mar 1, 2022

Choose a reason for hiding this comment

samestep Mar 1, 2022

Choose a reason for hiding this comment

samestep Mar 1, 2022

Choose a reason for hiding this comment

samestep Mar 1, 2022

Choose a reason for hiding this comment

cmumatt commented Mar 1, 2022

cmumatt commented Feb 28, 2022 •

edited

codecov bot commented Feb 28, 2022 •

edited

cloudflare-pages bot commented Feb 28, 2022 •

edited

maxkrieger commented Feb 28, 2022 •

edited