Skip to content

readme.md

Latest commit

 

History

History
64 lines (32 loc) · 3.84 KB

readme.md

File metadata and controls

64 lines (32 loc) · 3.84 KB

Internal docs authoring notes

deploying to readme.io

When you edit the docs in /docs/readme-sync/ and merge to the master branch, you trigger a Travis build stage (readme-sync) that syncs the Markdown doc files to FullStack public docs at https://docs.developers.optimizely.com/full-stack/docs/optimizely-agent.

If for any reason the travis build isn't working, you can publish the docs from GitHub to readme.io manually. For the sync tool's readme see https://github.com/flowcommerce/readme-sync. Here are quick instructions:

  1. clone https://github.com/flowcommerce/readme-sync to an environment in which you've installed Node & NPX.
  2. clone this agent repo
  3. Record the API key for the the full stack docs project (https://dash.readme.com/project/full-stack/v4.0/api-key)
  4. From the readme-sync cloned directory, run the sync for the docs version you want using the API key and the local directory path to the docs, i.e: npx ts-node sync/index.ts --apiKey <your_api_key_here> --version 4.0 --docs ~/Github/agent/docs/readme-sync/v4.0 and npx ts-node sync/index.ts --apiKey <your_api_key_here> --version 3.1 --docs ~/Github/agent/docs/readme-sync/v3.1

Previewing

Before you commit to master, there's a travis stage that syncs your branch's changes to a ReadMe sandbox so you can preview the published output, https://docs.developers.optimizely.com/full-stack/docs/ (you need to be logged into ReadMe to see this sandbox, since it's not public).

Directory and filename requirements

See https://github.com/flowcommerce/readme-sync.

Authoring requirements & limitations

You can author the docs in Github-flavored Markdown, with the following minor restrictions and caveats:

  • links - You can use relative links, but you have to leave out the .md extension. Like this: relative link to a doc. (Future improvement: should be easy to modify readme-sync code to strip out .md extensions if we want working relative links in the markdown stored in github)
  • images - You can't use relative links. Currently, we use hyperlinks to images stored on the master branch like this.
  • manual edits to updatedAt: the frontmatter in each markdown page includes an updatedAt field, which you must manually edit when you commit a page, so that the public docs display the correct info at the bottom of the page ("Updated x days ago").
  • no semantic code snippets / language highlighting ReadMe gets confused if you use a code block snippet that indicates the language. It erratically interprets #code comments as heading markdown syntax. So if you have a bunch of headings, then avoid:
# some python code here

and only use:

# some code in some unspecified language here
  • no authoring in dash.readme - If someone doesn't know better, they could edit the Agent docs in dash.readme... but those edits will be overwritten the next time triggers the readme-sync Travis stage. There's no mechanism in dash.readme to warn them not to edit. Likewise, any suggested edits in ReadMe need to be manually merged to the Github docs rather than merged using ReadMe's mechanism.

Future improvements

  • build conflict resolution - If 2 Travis builds tried to sync to readme at the same time, one could overwrite the other. Build duration is ~5 minutes. (One way to get to eventual consistency might be to run a nightly Travis build that syncs to Readme.)
  • no automatic updates to readme-sync - The engine for this sync is an externally developed tool that uses the ReadMe API called readme-sync. We clone readme-sync not from the public repo, but from a mirrored repo (https://travis-ci.com/github/optimizely/readme-sync2) that was set up in early 2020. So over time we'll miss out on updates to readme-sync https://github.com/flowcommerce/readme-sync.