[WIP] Prototype doc site #1369

carolynvs · 2017-11-12T03:38:54Z

What does this do / why do we need it?

This is a prototype for a dep doc site. You can see an example of it at https://carolynvs.github.io/depdocs/.

It uses Hugo as the static site generator.
The docs source continue to be located in /docs, and are versioned along with the dep code.
The site is hosted on github pages and the generated files are in the gh-pages branch. This branch should never be manually tweaked as changes will be lost on the next push.
The site would be located at https://golang.github.io/dep/.
Travis is configured to generate the site for pushes to master, and for tagged releases.
Tagged releases are published to /releases/vX.Y.Z/. The sidebar links to these manually (but an enterprising person would be welcome to automate this part).
We will not go back and update older releases doc. Whatever was present when we tagged, is what is included.
There is an encrypted deploy key checked into hack which travis uses to push to gh-pages. PR builds do not have access to this, it's only decrypted for merged code.
The modified/forked theme is located at https://github.com/carolynvs/hugo-alabaster-theme/tree/depdocs. I am exporting it and checking it into our repo so that we don't mess with submodules or anything fussy.

Before we merge this the following should occur. I'll do this on this PR after we are sure we want to accept this PR:

Remove the old standalone doc files and move the content into the generated site.
Update all links
Remove duplicate content from the readme and link to the site. We'll keep dev specific sections like contributing/feedback, but usage, etc should not be duplicated.
Document how to preview the site locally (here's the makefile I am using in the example site)
Add the deploy key to this repo.

What should your reviewer look out for in this PR?

Is this a workable initial setup for our doc site?

What is not in scope?

It doesn't have to be a drop in / migration ready setup for when dep is merged into the toolchain.
I don't have any frontend aspirations and would like to avoid any changes to the theme or visuals. Hopefully we can find someone with more design skills to tackle and incrementally improve the site.
I'm explicitly not adding new content or majorly reorganizing it. Once we have the infrastructure in place, we can tweak from there.

Do you need help or clarification on anything?

I don't believe so.

Which issue(s) does this PR fix?

Fixes #331. Or at least it's a start. 😀

sdboyer · 2017-11-28T15:01:46Z

ok so, we definitely want to do this 😄

i'll try for more review today or tomorrow, but in the meantime, do you think we could reasonably do some of those checkboxes in stages?

darkowlzz

I tried it, works and looks great.
I've left a few inline comments about the broken links. But I feel, since there's a lot of text, we can fix them gradually later. Maybe get help from the readers?

darkowlzz · 2017-11-30T11:39:44Z

docs/content/index.md

+At this stage, the maintainers are most interested in feedback centered on the user experience (UX) of the tool.
+Do you have workflows that the tool supports well, or doesn't support at all?
+Do any of the commands have surprising effects, output, or results?
+Please check the existing issues and [FAQ](docs/FAQ.md) to see if your feedback has already been reported.


Link seems to be broken. [FAQ](faq) works.

darkowlzz · 2017-11-30T11:40:25Z

docs/content/index.md

+  - [User Stories](https://docs.google.com/document/d/1wT8e8wBHMrSRHY4UF_60GCgyWGqvYye4THvaDARPySs/edit)
+  - [Features](https://docs.google.com/document/d/1JNP6DgSK-c6KqveIhQk-n_HAw3hsZkL-okoleM43NgA/edit)
+  - [Design Space](https://docs.google.com/document/d/1TpQlQYovCoX9FkpgsoxzdvZplghudHAiQOame30A-v8/edit)
+- [Frequently Asked Questions](docs/FAQ.md)


docs/FAQ.md -> faq

darkowlzz · 2017-11-30T11:44:56Z

docs/content/usage.md

+
+## Installing dependencies
+
+(if your `vendor/` directory isn't [checked in with your code](docs/FAQ.md#should-i-commit-my-vendor-directory))


docs/FAQ.md -> /dep/faq#...

darkowlzz · 2017-11-30T11:48:02Z

docs/content/setup.md

+1. Back up your existing `vendor/` directory (if you have one) to
+`_vendor-TIMESTAMP/`
+1. Pick the highest compatible version for each dependency
+1. Generate [`Gopkg.toml`](docs/Gopkg.toml.md) ("manifest") and `Gopkg.lock` files


This link would require docs/Gopkg.toml.md to be moved into docs/content/ and then change the link accordingly. Or maybe an external github link to the file.

darkowlzz · 2017-11-30T11:49:08Z

docs/content/setup.md

+
+This does the following:
+
+1. Look for [existing dependency management files](docs/FAQ.md#what-external-tools-are-supported) to convert


docs/FAQ.md -> /dep/faq#...

darkowlzz · 2017-11-30T11:50:42Z

docs/content/index.md

+Contributions are greatly appreciated.
+The maintainers actively manage the issues list, and try to highlight issues suitable for newcomers.
+The project follows the typical GitHub pull request model.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.


This link would require moving CONTRIBUTING.md into docs/content/. Or maybe an external github link would be good for it.

darkowlzz · 2017-11-30T11:54:34Z

.gitignore

+/docs/_deploy/
+/docs/_preview/
+/docs/config.toml.bak
+/hack/travis.deploy.pem


end with newline

carolynvs · 2017-12-02T13:54:53Z

@sdboyer Yeah, all the checkboxes can be done later, though if we want deploys to work, adding the deploy key to the repo is not optional. Everything else can be done later and I think we should.

sdboyer · 2017-12-03T21:07:15Z

let's just get the deploy key in here, then. I'm not clear on what we need to do there, though - just enter it into Travis via their mechanism for secrets?

carolynvs · 2017-12-03T21:33:37Z

@sdboyer On the repo, click Settings -> Deploy Keys -> Add Deploy Key, then paste the public key from my pull request (below). The private key has been encrypted with the travis tool for this repo only, and can only be decrypted during a travis build on master (i.e. not forks).

https://github.com/golang/dep/pull/1369/files#diff-4792ccfc9d3ef656e9cb864451527ea5

carolynvs · 2018-01-08T15:21:12Z

Closing in favor of #1499

sdboyer · 2018-01-08T19:42:39Z

y'know i think actually we could probably set up docusaurus before the docs themselves are merged. just...not publicize it until it's got content there😁

carolynvs · 2018-01-09T15:29:33Z

@sdboyer Is that a hint? 😁

sdboyer · 2018-01-09T16:15:44Z

it was actually just musing, not a hint, sorry - though if you had time to take it as a hint, i would be the opposite of unhappy about it 😉

carolynvs · 2018-01-10T19:53:53Z

@sdboyer I'll trade you looking at my transitive constraints PR/proposal, in exchange for setting up docusaurus.

Prototype doc site

1fb09a0

carolynvs requested a review from sdboyer as a code owner November 12, 2017 03:38

googlebot added the cla: yes label Nov 12, 2017

carolynvs requested review from jmank88, ibrasho and darkowlzz November 15, 2017 04:14

darkowlzz reviewed Nov 30, 2017

View reviewed changes

carolynvs mentioned this pull request Dec 13, 2017

Revert "Merge pull request #1405 from ibrasho-forks/prune-docs" #1451

Merged

carolynvs closed this Jan 8, 2018

carolynvs deleted the docs branch February 11, 2018 19:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Prototype doc site #1369

[WIP] Prototype doc site #1369

carolynvs commented Nov 12, 2017 •

edited

Loading

sdboyer commented Nov 28, 2017

darkowlzz left a comment

darkowlzz Nov 30, 2017

darkowlzz Nov 30, 2017

darkowlzz Nov 30, 2017

darkowlzz Nov 30, 2017

darkowlzz Nov 30, 2017

darkowlzz Nov 30, 2017

darkowlzz Nov 30, 2017 •

edited

Loading

carolynvs commented Dec 2, 2017

sdboyer commented Dec 3, 2017

carolynvs commented Dec 3, 2017

carolynvs commented Jan 8, 2018

sdboyer commented Jan 8, 2018

carolynvs commented Jan 9, 2018

sdboyer commented Jan 9, 2018

carolynvs commented Jan 10, 2018


		## Installing dependencies

		(if your `vendor/` directory isn't [checked in with your code](docs/FAQ.md#should-i-commit-my-vendor-directory))


		This does the following:

		1. Look for [existing dependency management files](docs/FAQ.md#what-external-tools-are-supported) to convert

[WIP] Prototype doc site #1369

[WIP] Prototype doc site #1369

Conversation

carolynvs commented Nov 12, 2017 • edited Loading

What does this do / why do we need it?

What should your reviewer look out for in this PR?

What is not in scope?

Do you need help or clarification on anything?

Which issue(s) does this PR fix?

sdboyer commented Nov 28, 2017

darkowlzz left a comment

Choose a reason for hiding this comment

darkowlzz Nov 30, 2017

Choose a reason for hiding this comment

darkowlzz Nov 30, 2017

Choose a reason for hiding this comment

darkowlzz Nov 30, 2017

Choose a reason for hiding this comment

darkowlzz Nov 30, 2017

Choose a reason for hiding this comment

darkowlzz Nov 30, 2017

Choose a reason for hiding this comment

darkowlzz Nov 30, 2017

Choose a reason for hiding this comment

darkowlzz Nov 30, 2017 • edited Loading

Choose a reason for hiding this comment

carolynvs commented Dec 2, 2017

sdboyer commented Dec 3, 2017

carolynvs commented Dec 3, 2017

carolynvs commented Jan 8, 2018

sdboyer commented Jan 8, 2018

carolynvs commented Jan 9, 2018

sdboyer commented Jan 9, 2018

carolynvs commented Jan 10, 2018

carolynvs commented Nov 12, 2017 •

edited

Loading

darkowlzz Nov 30, 2017 •

edited

Loading