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.

Sign up for GitHub

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

Jump to bottom

Documentation Website #19

Merged
merged 122 commits into from
Aug 2, 2023
Merged

Documentation Website #19

merged 122 commits into from
Aug 2, 2023

Conversation

freshgum-bubbles
Copy link
Owner

@freshgum-bubbles freshgum-bubbles commented Jun 25, 2023 •
edited
Loading

The main goal of this project is to create a better TypeDI. Also, one that I and others can use in projects.
Without documentation, that's quite hard to do.

Therefore, this PR begins work on a documentation website.
This will most likely be hosted through GitHub Pages.

Checklist

  • API Reference
    Implementation notes: This might be a bit harder to do nicely. The output from the TypeDoc Markdown plugin is... very ugly in Docusaurus. It might be better to build the Docusaurus website, and then tell TypeDoc to output the API reference to the build directory. It won't integrate with Docusaurus at all, but it renders a lot nicer.
  • Getting Started
  • Guides on how to use various container features (eager, multiple, scopes)
  • JSService docs
  • Destroying containers
  • Warnings (footguns)
  • Container creation options
  • Tree Visitors
  • StackBlitz / CodeSandbox in-browser demo (think https://docusaurus.io/docs/playground)

Known issues:

  • It's not currently possible to sync the light / dark mode between TypeDoc and Docusaurus.
    TypeDoc is pretty hard to extend without forking the whole thing.

Currently, this is not ready to merge.

Fixes #20.
Fixes #51.
Fixes #7.
Fixes #29.
Fixes #36.
Fixes #52.

@freshgum-bubbles freshgum-bubbles added documentation Improvements or additions to documentation enhancement New feature or request labels Jun 25, 2023
@freshgum-bubbles freshgum-bubbles mentioned this pull request Jun 25, 2023
Open
@freshgum-bubbles
Copy link
Owner Author

Update: Documentation coming along nicely!

Writing the documentation for resolution constraints now.
Thankfully the API surface is (relatively) simple, so there's not a lot of work to do.

To anyone reading this: Once this is published, I would really appreciate some eyes
on the documentation. I'm not an avid docs writer, so there may be some things which
could be improved.

@freshgum-bubbles freshgum-bubbles self-assigned this Jun 28, 2023
@freshgum-bubbles freshgum-bubbles mentioned this pull request Jun 24, 2023
Open
3 tasks
@freshgum-bubbles
Copy link
Owner Author

freshgum-bubbles commented Jul 2, 2023 •
edited
Loading

Update: the documentation has been revised.
Much of the work was focused on improving the homepage, which previously
hosted the built-in Docusaurus template.

Before:
image

After:
image

Admittedly, a bit of work still needs to be done.
The code is quite sloppy, with a lot of repeated code (see the inputs in the demo's).

Further, some elements like the demo's aren't correctly aligned, and their use of
colours does look a bit strange.
Oh, we need to make it responsive too.

Todo:

  • Make home page responsive
  • Clean up demo code (remove repeated code, abstract input into component, etc.)
  • Fix vertical alignment of demo components on the right
  • Fix the bloody light theme (it's horrendous)
  • Fix admonition backgrounds to have better contrast ratios.
    image

@freshgum-bubbles freshgum-bubbles added this to the Version 1 milestone Jul 4, 2023
@freshgum-bubbles freshgum-bubbles force-pushed the docs/initial-docs branch 7 times, most recently from 330f8d7 to 95ac670 Compare July 18, 2023 18:22
@freshgum-bubbles
docs(website): add initial Docusaurus website
a0f4115
@freshgum-bubbles
docs(website): remove Gitbook config
7254f1d 
This file is no longer required, as the
new project will not be making use of
GitBook.
@freshgum-bubbles
refactor(docs): remove old documentation
d7856af 
Remove any remnants of the old .md
documentation files from upstream TypeDI.
@freshgum-bubbles
docs(website): remove Docusaurus docs
161c8a4 
Remove the Docusaurus default doc files
from the repository.
@freshgum-bubbles
fix(website): update Docusuarus config
dc86c1a 
Update the configuration to change the name
of the project, links, templates, and more.
@freshgum-bubbles
docs(website): add initial documentation
0288b09
@freshgum-bubbles
docs(website): update Hello World example
9f681e5
@freshgum-bubbles
docs(website): add initial NodeJS web server example
5085fe2 
This is incomplete, and will be revised in a future commit.
@freshgum-bubbles
docs(website): add license file
4a1b182
@freshgum-bubbles
docs(website): add Code of Conduct
8516079
@freshgum-bubbles
chore(website): add robots.txt
5bf1e4c
@freshgum-bubbles
docs(website): add skeleton for Best Practices section
1288a1e
@freshgum-bubbles
refactor(website): update configuration management
f483ee6 
Add a set of custom fields alongside a decorator that
returns the custom fields in a typed manner.
This is required as the original decorator from Docusaurus
types customFields to a generic Record type.
@freshgum-bubbles
refactor(website): use new useAppContext hook
b1258d2 
Use the hook created in the previous commit.
@freshgum-bubbles
feat(website): add support for Mermaid
36c4bf1 
This will be used for generating graphical
flow charts later on.
@freshgum-bubbles
Copy link
Owner Author

I think we can safely merge this now, and continue work in develop.

@freshgum-bubbles freshgum-bubbles marked this pull request as ready for review July 31, 2023 15:29
@freshgum-bubbles freshgum-bubbles merged commit 5253cb3 into develop Aug 2, 2023
@freshgum-bubbles freshgum-bubbles deleted the docs/initial-docs branch August 2, 2023 16:05
@freshgum-bubbles freshgum-bubbles mentioned this pull request Aug 2, 2023
Merged
2 tasks
@github-actions
Copy link
Contributor

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Sep 10, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers
No reviews
Assignees

@freshgum-bubbles freshgum-bubbles

Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Milestone
Version 1
1 participant
@freshgum-bubbles