Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add auto-generated API documentation #3251

Merged
merged 2 commits into from
Nov 8, 2021
Merged

Add auto-generated API documentation #3251

merged 2 commits into from
Nov 8, 2021

Conversation

blueridger
Copy link
Member

@blueridger blueridger commented Nov 2, 2021

Description

The goal of this PR is to create a solution for computer-generated documentation. It includes these pieces:

  • Added documentation dependency to the mono-repo root
  • Added a yarn script and bash script for generating the docs. Usage: yarn docs at either the root or package level
  • Ran the script to generate docs for sourcecred 0.10.0
    • Note: I put this in a separate commit to make reviewing easier

The docs aren't super great, but they are a decent start (better than nothing) and they are at least highly searchable.

What this PR means for maintenance is that when someone is doing a version release, they can also update the docs with yarn docs

This also means that we will need to be more on top of using /** */ docstrings on everything we want in the API docs.

Design choices

I don't know how to design for mono-repos very well yet, so if something I've done is super tacky, let me know what a better way to do it would be. It seems simple and maintainable enough as I've done it.

Docs are put into a /docs folder for github pages compatibility. I figure we can just serve gh-pages out of main.

Each package will have its own folder in the site, and the script will set the currently generated docs as the default root "latest" (replacing the existing latest) and then also create an archival duplicate under a version-named folder.

Test Plan

Docs viewing

Open the html file you want to look at in a browser

Docs generation script

  • yarn docs at root level
  • yarn docs at package level
  • edit a docstring and rerun script, verify docs have been over-written
  • change version number and rerun script, verify "latest" default docs have been over-written and new version archive added

Copy link
Contributor

@hozzjss hozzjss left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good lfg

@blueridger blueridger merged commit a40646a into main Nov 8, 2021
@blueridger blueridger deleted the docs branch November 8, 2021 16:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants