Define MVP

[keithlayne]

What are the immediate goals?

Trying to sum up what was discussed on discord:

• Use ghpages for POC
• Have a periodic GH action that works off of some kind of work queue to build pages

Talked about:

• Limiting scope initially to a subset of npm
• Maybe ignore cross-linking for now

[cspotcode]

I invited you to be a maintainer of this repository. I added some MVP stuff to the readme, but feel free to delete what I wrote and instead link to this issue.

[cspotcode]

I copy-pasted a nightly GH Actions runner from another project, hopefully to serve as inspiration for anyone who might want to attempt an implementation.

[cspotcode]

Should we mention "typedoc" explicitly since the choice of documentation tool has been a question on Discord?

[tjjfvi]

Should we mention "typedoc" explicitly since the choice of documentation tool has been a question on Discord?

I mean, the repo is named typedoc-auto-docs

[cspotcode]

Haha, point taken.

[keithlayne]

I was slow and my issue is way less useful than the readme.

I haven't done much with ghpages, I thought there were multiple options for how to set it up in addition to a dedicated branch, but that's all I see in the settings. Who has experience with that? I assume like on the comment in the workflow file we'll need to build and push to the docs branch?

[tjjfvi]

I've used peaceiris/actions-gh-pages in the past, and it's been rather nice

[cspotcode]

I have a bunch of experience with ghpages. Admittedly that may make me biased.

There are multiple options. The one I always use -- for no particular reason -- is the gh-pages branch. Any files pushed to the gh-pages branch are served as a static site. This means you can use whatever git commands you want to push static files into that branch. You can choose to commit changes to single directories, you can choose to force-push and replace the entire thing, whatever is the easiest.

[keithlayne]

yeah, I forgot. I realized that you can pick a path after you pick a branch. Do you keep history on your gh-pages branch? Force-pushing sounds pretty reasonable for something like this.

[cspotcode]

I don't think history is important. However if we want our worker script to build and push docs for a single library at once, this may mean it is easiest to commit changes to a single subdirectory at a time.

For example, for an MVP our worker script might be doing something like this:

cd gh-pages-subdirectory
git checkout gh-pages
cp ../some-docs-rendered-here './libA@semver-range'
git add './libA@semver-range'
git commit -m "Adding rendered docs for libA@semver-range"
git push

[cspotcode]

We might be able to use some slick git commands in the future to avoid checking out the full gh-pages branch, since it will get big. And in the future future we can replace these git commands with aws s3 push or something like that

[keithlayne]

Yeah I was thinking shallow clone, update, force push. I was also thinking that the script would hit the npm (or whatever) API to see if each lib is out of date, then just build each as needed. But simpler is better.

Your way simplifies several things too.

[cspotcode]

Ah, yes, npm API makes sense to me.

…

On Tue, Jul 13, 2021, 5:56 PM Keith Layne ***@***.***> wrote: Yeah I was thinking shallow clone, update, force push. I was also thinking that the script would hit the npm (or whatever) API to see if each lib is out of date, then just build each as needed. But simpler is better. Your way simplifies several things too. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAC35OESV4VWFVNNZVU7RE3TXSZCVANCNFSM5AKB2ZQA> .