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 docs website #43

Merged
merged 9 commits into from
May 31, 2023
Merged

Add docs website #43

merged 9 commits into from
May 31, 2023

Conversation

jcbhmr
Copy link
Collaborator

@jcbhmr jcbhmr commented May 30, 2023

This PR would...

  • Add TypeDoc as a dev dep https://typedoc.org/
  • Auto-generate a website and deploy it to GitHub Pages using GitHub Actions on each Release
  • Change package-lock.json
  • Add typedoc config in tsconfig.json
  • Create a website that can go on Google

Note that you'd need to make sure that GitHub Pages in Settings tab is set to receive from GitHub Actions. By default it's set to OFF.

image

You can view the website yourself on GitHub Codespaces via the "Code" dropdown on this PR, then run:

npm run build-docs
python -m http.server -d docs/dist

You could change:

  • the npm run build-docs script to be whatever name you want
  • the out folder from docs/dist to _site or .typedoc or whatever

I'd recommend adding more extensive JSDoc blocks with @example and other documentation stuff to each of the functions. This would help the doc gen and the tooltip hovers in VSCode and other LSP editors. Here's what isPlainObject() looks like right now:

image

Note that right now "is-what" is terrible for Google SEO since even refinements like "is-what npm" or "is-what github" all are like "What is GitHub?" and "What is npm? A quick intro." instead of this package. 🤣 I think that a website would be a good idea to make a presence for Googlers and also provide valuable documentation overview that is generated from code and doesn't need to be custom-made in the readme. Specifically, examples are CRUCIAL.

@mesqueeb mesqueeb changed the base branch from production to dev May 31, 2023 01:04
@mesqueeb
Copy link
Owner

@jcbhmr thank you so much

adding more extensive JSDoc blocks with @example and other documentation

made an issue for this: #45

will this also improve SEO?

@mesqueeb mesqueeb merged commit c710445 into mesqueeb:dev May 31, 2023
@jcbhmr
Copy link
Collaborator Author

jcbhmr commented May 31, 2023

You're welcome! Thanks for fixing the mistakes I had 😬 oopsies on me for opening PRs with literal non-working code. my bad.

I think the examples a) make the docs better b) improve knowing what the function does c) document edge cases like null-prototype objects, etc. and c) make the website "full" in the eyes of our GoogleBot overlords so that it ranks higher and is not just a "stub website"

@jcbhmr jcbhmr deleted the add-docs branch May 31, 2023 01:43
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