You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
what about using a docs/ on the master branch? This could be generated during a release script, so things would stay in-sync and might be easier to maintain?
I understand that it's a common thing for repo's to use gh_pages, but it seems much more streamlined if the docs lived with the code, at least from a users perspective.
If you are going to be having typescript types in the main branch, then why not docs?
It's also pretty common to have generated docs in /docs on master. It's the default option in the repo settings. I'm not sure what the concern is tbh - I just thought it was a minor thing to argue about. I want to set up a GH Action that generates the docs with each push to master. It should be pretty straightforward using something like https://github.com/crazy-max/ghaction-github-pages
It's common in git to not push generated files in master. Putting generated files makes searching worse, docs out of date, etc. For example, CSS files and font files shouldn't be in this repo.
Most top npm modules don't have generated docs, markdown is fine.
If you are going to be having typescript types in the main branch, then why not docs?
There are no typescript types files, assuming you're referring to .d.ts files. Only source code.
i'm suggesting that you just use "docs/" on the main branch.
docs out of date
The docs only really get updated during a version release, and there already is a "release" script in the package.json, it is pretty easy to just add the generate_docs script to that.
Activity
lholmquist commentedon Jun 8, 2020
what about using a
docs/on the master branch? This could be generated during a release script, so things would stay in-sync and might be easier to maintain?lance commentedon Jun 8, 2020
That's how it has been, but @grant pushed back on that for some reason.
lholmquist commentedon Jun 8, 2020
I understand that it's a common thing for repo's to use gh_pages, but it seems much more streamlined if the docs lived with the code, at least from a users perspective.
If you are going to be having typescript types in the main branch, then why not docs?
lance commentedon Jun 8, 2020
It's also pretty common to have generated docs in
/docsonmaster. It's the default option in the repo settings. I'm not sure what the concern is tbh - I just thought it was a minor thing to argue about. I want to set up a GH Action that generates the docs with each push tomaster. It should be pretty straightforward using something like https://github.com/crazy-max/ghaction-github-pagesgrant commentedon Jun 8, 2020
It's common in git to not push generated files in
master. Putting generated files makes searching worse, docs out of date, etc. For example, CSS files and font files shouldn't be in this repo.Most top npm modules don't have generated docs, markdown is fine.
There are no typescript types files, assuming you're referring to
.d.tsfiles. Only source code.lance commentedon Jun 8, 2020
Re: generated files... unless you are volunteering to write the API documentation, I think we're going to go ahead and generate the docs
grant commentedon Jun 8, 2020
Generating docs on
gh_pagesSGTM as before.Not sure what @lholmquist is suggesting.
lholmquist commentedon Jun 8, 2020
i'm suggesting that you just use "docs/" on the main branch.
The docs only really get updated during a version release, and there already is a "release" script in the package.json, it is pretty easy to just add the generate_docs script to that.
docs: generate api documentation as a GitHub workflow
docs: generate api documentation as a GitHub workflow
docs: generate api documentation as a GitHub workflow
docs: generate api documentation as a GitHub workflow (#217)