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

Asciidocs and refdocs tooling #648

Merged
merged 2 commits into from
Jun 8, 2018

Conversation

balopat
Copy link
Contributor

@balopat balopat commented Jun 7, 2018

This is in context of #629.

See generated example:

Documentation tooling requirements:

  • Written in a format that is renderable on Github
  • Content is accessible through an outline (sidebar preferably)
  • Enables easy PR workflows
  • Easy to review changes
  • Easy for a contributor to propose changes

Additional goals:

  • Composable pages to reduce duplication
  • Ability to style/brand
  • Satisfy the following layout goals:

Layout goals:

  • Have a great, searchable single page HTML with a clear outline (the same for the PDF)
  • Support Github as a renderer
    • Have a full Github landing page (just like currently)
    • The examples would still live in their separate folders as standalone documented examples, with a good Github specific README with table of contents
  • Keep duplication minimal
    • The first chapter of the reference docs would come mostly from the Github landing page
    • Examples would be included in the reference docs

Copy link
Contributor

@dgageot dgageot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice!

docs/index.adoc Outdated
:doctype: book
:github-repo-tree: http://github.com/GoogleContainerTools/skaffold/tree/{commit}

=====
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide these from the github preview if you can

@dgageot
Copy link
Contributor

dgageot commented Jun 8, 2018

Sorry @balopat, you have to rebase

@balopat balopat merged commit f6fe0de into GoogleContainerTools:master Jun 8, 2018
@balopat balopat deleted the asciidocs branch June 8, 2018 18:16
steps:
# Build the container that will do the go build.
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', 'gcr.io/k8s-skaffold/skaffold:$TAG_NAME', '-f', 'deploy/skaffold/Dockerfile', '.']
# Do the go build.
- name: 'gcr.io/k8s-skaffold/skaffold:$TAG_NAME'
args: ['make', 'cross']
args: ['make', 'cross', 'docs']
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this fails @balopat
docker is not in the integration test image. I would move this to a separate step (I don't want to add asciidoctor to the integration/published skaffold image

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds good. I'll fix it up.

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

Successfully merging this pull request may close these issues.

3 participants