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.

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

Use github pages for this repo #78

Open
eteq opened this issue Feb 5, 2019 · 1 comment
Open

Use github pages for this repo #78

eteq opened this issue Feb 5, 2019 · 1 comment

Comments

@eteq
Copy link
Contributor

eteq commented Feb 5, 2019

Some feedback from @hcferguson and a few other folks I've talked to about the style guide: for those who aren't used to seeing GitHub a lot, they get lost and give up perusing the style guides because the page is full of github distractions instead of being focused on the style guides themselves. Moreover, updating the README is a constant chore (e.g. #82): because there's now several people writing the style guides, the manual update step means the README is constantly behind the guides.

This could be easily rectified by having the content of the style guides be on GitHub Pages. More concretely:

  1. the README could be pared down to the intro paragraph plus a "follow this link to see the rendered style guides"
    2a. GitHub Pages' built-in Jekyll support could be used since this is a static site.
    2b. We can set up a lightweight CI build that either uses some other static site generator or just a dead-trivial script that uses pandoc or some other markdown-to-html converter to make the HTML pages for the guides.
  2. Auto-generate an index / Table of Contents with whatever framework is chosen in 2

Downside is that this might be over-automating a problem that we should just instead use maintainer discipline to enforce (the README thing, I mean)...

cc @arfon @stscicrawford

@arfon
Copy link
Contributor

arfon commented Mar 11, 2019

Yeah, this is a good idea I think.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants