feat: Replacement to TSDoc for API documentation

honojs / website

Repository for hono.dev

https://hono.dev

68 stars 208 forks source link

feat: Replacement to TSDoc for API documentation #375

Closed 6km closed 2 weeks ago

6km commented 1 month ago

As [proposed by @yusukebe (Replacement to TSDoc for API documentation)(https://github.com/orgs/honojs/discussions/2854).

I will be working on implementing this in the meantime.

Main goals:

API references should have a similar style and format to the Docs.
For faster maintenance, auto-generate with every new build of the site.

API docs automatic generation process:

Clone source code from honojs/hono in a temporary folder
Run typedoc to generate the docs
Delete source code files of Hono
Run the usual build process...

Thanks for discussing the proposal:

@goisaki
@yusukebe
@NicoPlyley

6km commented 1 month ago

Hi @yusukebe

What do you think about the API docs generation process?

API docs automatic generation process:

Clone source code from honojs/hono in a temporary folder

Run typedoc to generate the docs

Delete source code files of Hono

Run the usual build process...

yusukebe commented 3 weeks ago

@6km

Yeah. I also think in a similar way.

Clone source code from honojs/hono in a temporary folder

I think we cah use like Git submodule feature.

6km commented 3 weeks ago

@yusukebe Can we use tiged to clone the soruce code from honojs/hono? It's used by create-hono to clone started templates too!

goisaki commented 3 weeks ago

Hi @yusukebe and @6km I don't understand the need to use a submodule, so I think this is a simple way to do it:

- name: Checkout
  uses: actions/checkout@v4
  with:
    path: website

- name: Checkout code repo
  uses: actions/checkout@v4
  with:
    repository: honojs/hono
    path: hono

In this case, the next challenge is

How do we run workflow as we upgrade?
- Manual (not good)
- Automatic (good, but hard)

yusukebe commented 3 weeks ago

@goisaki

I don't understand the need to use a submodule, so I think this is a simple way to do it:

Yeah, you are right. I thought it is necessay for local development to refer the honojs/hono repository, but we can specify the path manually or an environment variable.

In this case, the next challenge is

Yes. Our challenge is to create the GitHub actions to automate updating the docs.

yusukebe commented 3 weeks ago

The ideal flow is the following:

honojs/hono main branch will be updated.
This honojs/website repo will receive the notification.
Check out the honojs/hono repo in GitHub Actions.
Build the docs in GitHub Actions.
git add, git commit, and git push the changes.
The website https://hono.dev will be updated.

It's difficult to try it in the current repo, so I think we have to do them in each private repo.