search

d3-geomap / site

Source for d3-geomap documention website.
https://d3-geomap.github.io/
0 stars 0 forks source link

Consolidate examples in the library source and example maps on the docs site #2

Open yaph opened 5 years ago

yaph commented 5 years ago

I'd like to have examples only in one place, preferably the documentation website. I realize that not everyone looks at the site and shipping some examples with the library source may make sense. At this point adding an example in the library is a bit of a pain and I want to reduce the maintenance burden.

I'm interested in feedback from people who use this library. If you are one of those and have an opinion on this topic or a suggestion, please share it in the comments of this issue.

dpraul commented 5 years ago

Since you're already using GitHub Pages, it's quite easy to setup an automatic deployment script from a cloud-hosted Continuous Integration provider. Pretty "tried and true" options include Travis CI and CircleCI, and GitHub now offers GitHub Actions.

I'd recommend moving the source code of this repo into the main d3-geomap repository under a "demos" or "docs" folder, and setting up a CI system to build & test commits. When changes are made to master, build the contents of the demo/docs site and push them to here (or to a local gh-pages branch of the d3-geomap repo).

I've done and seen this done in many iterations, and I'm sure you can find how-to guides for GitHub Pages deployment from CI for any of the CI options. Here's a not especially robust but also not very complicated example using CircleCI: .circleci/config.yml and ghpages-deploy.sh

I don't think you should ship these examples with the library source, though. Better documentation with JSDoc or some more-complicated-but-more-robust TypeScript types would go a long way. Dropping URLs to the demo site in relevant places of the docs would be sufficient and is a pattern I've seen done elsewhere.

yaph commented 5 years ago

Thanks for your input Dylan! I prefer to keep the docs site and library repos separately to avoid adding another layer of complexity and technologies to the library repo. Adding the docs site as a git submodule to the library could be an option though. I think automating the deployment of the docs site should work with GitHub actions too when using submodules.