Skip to content

Latest commit

 

History

History
246 lines (173 loc) · 10.5 KB

README.md

File metadata and controls

246 lines (173 loc) · 10.5 KB
Raw
authors state
Trent Mick <trent.mick@joyent.com>
publish

RFD 23 Manta docs pipeline

Here in the docs plan for Manta (where primary sources live, how to build them, how to publish them). If this document and reality differ, then someone hasn't kept this up to date. :)

The Manta docs are spread across a few repositories, and publishing is to more than one site (and sites that also publish docs for other projects). For a while (up to Jan 2016) the publishing pipeline was effectively broken: the published docs at apidocs.joyent.com were not updatable from primary sources. Hence this RFD to act as the authority for the plan.

Note that content on <www.joyent.com> for Manta is out of scope for this RFD.

Manta docs pipeline

Sources

The primary Manta docs are Markdown files in a number of git repositories.

Repo Description
manta.git General Manta intro/landing-page is the repo README.md. Operator Guide. User Guide.
manta-muskie.git Manta REST API docs
node-manta.git "Node.js SDK" docs: man pages and node.js library docs
manta-compute-bin.git Man pages for Manta compute job utilities, e.g. maggr, mcat.

Publish Targets

URL How to update Description
https://apidocs.joyent.com/manta How to update Manta user guide
https://github.com/joyent/manta How to update Manta project landing page for those with a code/operator interest
http://joyent.github.io/manta/ How to update (The somewhat hard to find) publishing of the manta operator guide
https://joyent.com/manta - Out of scope. Currently redirects to <joyent.com/object-storage>.

How to update the Manta User Guide

The published User Guide is made up of a number of separate logical groups. The first step is to find out which. Currently all results are dumped into one flat directory. Eventually those will be spread into logical separate dirs making identifying the source easier, but not yet.

Name URL pattern Source
api api.html https://github.com/joyent/manta-muskie/blob/master/docs/index.md
nodesdk nodesdk.html, m*.html https://github.com/joyent/node-manta/blob/master/docs, note some "m*.html" man pages in manta-compute-bin.git
compute-man-pages m*.html https://github.com/joyent/manta-compute-bin/tree/master/docs/man, note some "m*.html" man pages in node-manta.git
compute-examples example-*.html https://github.com/joyent/manta/tree/master/docs/user-guide/examples
base *.html (everything else) https://github.com/joyent/manta/tree/master/docs/user-guide

  1. Find the source group from the table above and edit source Markdown.

  2. Get a review from Manta developers (whether via 'manta@' internal chat, MANTA internal Jira ticket, email to Manta developers, GitHub PR, or #joyent IRC).

    Currently the build and publishing of the User Guide is done in a private apidocs.joyent.com.git repository, so non-Joyent employees will have to stop at this step.

  3. (For "compute-examples" group only.) The example-FOO.html files are built wholely in the "manta.git", and the resultant HTML is commited. The HTML is the output of a mjob share. The rebuild the full set of example files, you first need your SSH key on the Joyent "manta" account used to house the examples, then:

     cd manta/     # joyent/manta.git clone
 make docs-regenerate-examples

    See the examples README for details.

    Review and commit any HTML changes. Note: Because a re-run of a job changes its UUID, there will be a large change for what could be effectively no change. Try to avoid unnecessary churn.

  4. Re-import and build all Manta User Guide changes in a clone of apidocs.joyent.com.git:

     git clone git@github.com:joyent/apidocs.joyent.com.git
 cd apidocs.joyent.com
 make import-docset-manta
 # Follow printed instructions to 'git diff' and 'git commit'.

    You can optionally configure separate branches or git SHA revs for doc imports in the "etc/config.json" file.

  5. Talk to the master o' the docs (current MattF) to re-publish apidocs.joyent.com.

How to update the Manta Landing Page

  1. Update the manta.git README.md: https://github.com/joyent/manta/blob/master/README.md.

    Get a review from Manta developers (whether via 'manta@' internal chat, MANTA internal Jira ticket, email to Manta developers, GitHub PR, or #joyent IRC).

How to update the Manta Operator Guide

  1. Update the Markdown sources at https://github.com/joyent/manta/tree/master/docs/operator-guide.

    Get a review from Manta developers (whether via 'manta@' internal chat, MANTA internal Jira ticket, email to Manta developers, GitHub PR, or #joyent IRC).

  2. Publish via the make target in the manta.git repo:

     cd manta/         # joyent/manta.git clone
 make publish-operator-guide

The operator guide is currently published via GitHub Pages. Publishing is: (a) build the HTML from the Markdown (restdown) source, (b) update the gh-pages branch and push.

The Operator Guide styling is currently the default "ohthejoy" "brand" for the restdown tool being used to build it. Restdown is a light-weight wrapper for single-page Markdown docs (mostly just adding a TOC and some styling). The change the styling one would need to provide a custom restdown "brand". E.g. the restdown brand for Manta docs in apidocs.joyent.com, or the "remora" restdown brand currently used for cloudapi docs.

Future

Future plans/ideas.

  • follow up on mantadoc.git/docs/winmanta.md - Created, but never made it to deployment on apidocs.joyent.com that I can see. TODO: Do we want to clean it up and ship it? My pref would be to drop all/most of the screenshots of node install b/c maint burden.

  • Switch all manta restdown docs away from 'wiki-tables' to GH style tables

  • Consider the restdown-brand-remora (used for cloudapi docs) instead of "apidocs.joyent.com.git:etc/manta-brand" (a copy of the old mantadoc.git's "bluejoy" brand). This would align styles on apidocs.joyent.com. However, might also just want to move to the styles on docs.joyent.com. See the "longer term" TODO below.

  • Some sane hierarchical layout:

    • mjob examples in examples/$name/...
    • man pages in man/...

  • Having an "edit this" link on the footer of each doc automatically added which links to the relevant primary doc in GitHub would be pretty nice.

  • Longer term: The styling of docs on apidocs.joyent.com should move away from the current "bluejoy" theme (for manta docs) and "remora" theme (for others) to the same style as the docs.joyent.com docs.

  • Longer term: I consider apidocs.joyent.com a bug. Joyent is too small to have two separate doc sites. There whould be one "docs.joyent.com" with organized publishing of all our content. Same opinion for the Manta operator docs at <joyent.github.io/manta>. IMHO. Anyway, that is for another time.

History of Manta Docs state

state as of Jan 2016

DOC-642 will get us back to being able to update from primary sources.

state as of Dec 2015

Sources:

  • node-manta.git: "node.js SDK" docs
  • manta-muskie.git: Manta web front-end docs (mainly the REST API)
  • manta-compute-bin.git: man pages for Manta job utilities (e.g. maggr, mcat)
  • manta.git: General Manta intro/landing-page in the README.md, plus the operator guide and
  • mantadoc.git: A collection point for the other sources plus additional source content.

"Published" endpoints:

Update content for <joyent.github.io/manta>:

  • make docs
  • copy the index.html file into the "gh-pages" branch and push that

Updating content for <apidocs.joyent.com/manta>:

Sources:

  • node-manta.git: "node.js SDK" docs
  • manta-compute-bin.git: man pages for Manta job utilities (e.g. maggr, mcat)
  • manta-muskie.git: Manta web front-end docs (mainly the REST API)
  • manta.git: General Manta intro/landing-page in the README.md, operator guide, and (proposed) new source for the primary content in mantadoc.git.

Currently we are bound by the organization of the doc files as mantadoc.git has them. A downside of this plan is that it does mean that apidocs.joyent.com.git becomes the repo that knows how to lay things out. I'd hope to eventually make apidocs.joyent.com.git "dumb" in this regard: with manta.git being the repo that has the logical doc organization with places for the muskie and node-manta.git docs to slot in.

A reason I want to take mantadoc.git out of the picture is that I want to avoid a pipeline for doc fixes that involves three repos: (a) fix source doc in, say, manta.git; (b) update collected docs in mantadoc.git; (c) update for publishing in apidocs.joyent.com.git. I want to cut out repo (b).

Tickets