atomisthq / docs Goto Github PK

Currently when building semver tags, Travis CI pushes the built site to atomisthq.github.io/docs.atomist.com. Other builds should push the site to this repos gh-pages branch and the settings updated to use that branch for GitHub Pages.

/cc @jessitron

Inline with reviewed and updated https://github.com/atomisthq/atomist-internal-docs/blob/master/rug-conventions.md

The current Rug Conventions document has grown considerably and is beginning to break the navigation rendering. One option here is to attempt to break things out based on general purpose, Rug DSL and Rug TypeScript specific conventions. This might also prove more scalable generally as other JavaScript-transpiled options become available for Rug.

The new layout, which is much better, includes the title of the page from the mkdocs.yml config at the top of the page. The old layout did not. Because the old layout did not, many pages have similar headers at the top of their source. For example:

We need to go through mkdocs.yml config and make sure all the page titles are appropriate for displace in the page and go through all the pages and remove duplication between the page title and the initial header. I would guess we just need to remove most of the initial headers.

Rug 0.11.0 deprecated @generator with generator. Update the documentation.

For example if you are going to access the project from within a do block then you should name the selected type appropriately:

with file f when path = "README.md"
  do replace "{{creation_date}}" { f.name() + " created on " + new Date().toISOString().split('T')[0] }

However if the selected type is not being used then the name should be omitted:

with file when path = "README.md"
  do replace "{{creation_date}}" { new Date().toISOString().split('T')[0] }

https://atomist-community.slack.com/archives/general/p1485507291000818

From atomist-community: https://atomist-community.slack.com/archives/general/p1485334211000646

https://github.com/atomist/end-user-documentation/blame/8b360c6be32cbec03ac93a5520aac0958300a49a/docs/reference-docs/rug/types/rug-core-types-pom.md#L76

The documentation doesn't inform the user how to set a private repository to publish Rugs.

http://docs.atomist.com/reference-docs/rug/rug-cli-commands/

Each Type currently has Core Rug Type in front of it. Making it super tough to find stuff. This should be removed.

Currently, every Travis build pushes to the public site. Fix the build to only push for GitHub releases. This involves update the Travis configuration to create GitHub releases for tags that look like M.N.P semantic versions.

See rug-cli for an example.

The minimal contents of a Rug archive should also be shown and a link to a generator that does that work for you would be nice.

The Rug Koans are being extended and the documentation should link through to this self-directed learning approach for exploring Rug

Several new types were added. Others may have been updated. So update the docs.

Also change the file names from using rug-type to extension.

    publish: true
    url: "${MAVEN_BASE_URL}/rugs-dev"
    authentication:
      username: "${MAVEN_USER}"
      password: "${MAVEN_TOKEN}"

We need to add a section to the docs explaining how authentication can be configured in cli.yml.

The documentation would look clearer if the Rug DSL could be coloured to clarify what are the various elements it is made of.

Are all the rug-test / predicate assertions documented somewhere?

Our documentation doesn't warn that we can't install the CLI on old Debian/Ubuntu versions. This should be noted clearly to avoid misunderstandings.

Documentation and video.

e.g.

AssertContains content=bar, filename=foo

Make this:

link to www.atomist.com

Just wondered if we should look at something like http://readme.io/?

They have a very nice platform, theme and support for documentation (versionning, API, ...).

Releases are automatically pushed to docs.atomist.com but there is currently no automation around making every push available. See https://pages.github.com/ for information on using the gh-pages branch.

Are all the rug-test / predicate assertions documented somewhere?

There it could be useful to people

This has not been supported for some time:

http://docs.atomist.com/reference-docs/rug/escape/rug-clojure/#escaping-into-clojure-through-clojure-blocks

http://docs.atomist.com/reference-docs/rug/escape/rug-clojure/

http://docs.atomist.com/reference-docs/rug/types/rug-core-types-java-class/#operation-eval

We need to capture standards and best practices in a document. Things like what is that parameter name format camelCase/CamelCase/snake_case/kebab-case, common/recommended annotations, etc.

Early support for microgrammar's is now available in Rug so it's time to write this up, for reference initially.

http://docs.atomist.com/reference-docs/rug/types/rug-core-types-elm-module/

As far as I know, this is all UpperCamlCase now:

elm.module -> ElmModule

Currently there is a marker file there called rug-custom-types.md.

Currently the content around a day in the life of a rug archive doesn't include publication. This needs to be added.

The "Just get me going right now: Quick Starts" and "I want to know more: Reference Documentation" in the left-hand navigation box presumably are meant to jump to sections within the page, but since the page fits in a single pane, clicking on them does nothing. They should either be changed go to the actual page or be removed.

The current them the doc is using doesn't help navigating it. We need something better.