Skip to content

Latest commit

 

History

History
189 lines (121 loc) · 6.54 KB

README.md

File metadata and controls

189 lines (121 loc) · 6.54 KB
Raw

reaction-docs

📝 reaction-docs is the new static documentation generator for all Reaction Commerce projects.

Requirements

  • Node, 6.x and above
  • Yarn
  • Docker

Stack

  • Docusaurus, for static-site documentation generation
  • Markdown for Docs
  • React for components
  • highlight.js for JavaScript, HTML, CSS, shell syntax highlighting
  • Prism.js for JSX, GraphQL syntax highlighting
  • Algolia DocSearch
  • ESLint configured with Reaction Commerce eslint config
  • LiveReload during development
  • Docker

Contributing documentation

Run the docs website locally

git clone [email protected]:reactioncommerce/reaction-docs.git
cd reaction-docs
bin/setup
docker-compose up

Open http://localhost:4242

Update existing documentation

To update docs for the current released version of Reaction, edit existing Markdown files in website/versioned_docs.

  1. Find the Markdown file you want to edit in the latest version's folder, at website/versioned_docs/version-CURRENTVERSION. If the document you want to edit is not in that folder, check in previous versions' folders until you find the latest one.
  2. Edit the file and save.
  3. Go to http://localhost:4242/docs/<YOURMARKDOWNFILE_ID> to see your changes locally.

Documenting unreleased features, changes

To update docs of unreleased features, you will need to edit existing Markdown files in public_docs. For example, if you were documenting upcoming Reaction API changes to Cart that are merged into trunk but not yet tagged in a release, you'd update the public-docs/cart.md file.

  1. Edit the file and save.
  2. Go to http://localhost:4242/docs/next/<YOURMARKDOWNFILE_ID> to see your changes locally.

Documenting new, unreleased features

To create brand new documentation files for unreleased code that has previously not been documented, you will need to create new files in public_docs:

  1. At the start of the file, add the required frontmatter:
---
id: doc2
title: document number 2
---
  1. Add the Markdown file to the table of contents, at website/sidebars.json.
  2. When you update sidebars.json, you'll need to restart the app to see changes. Restart the app.
  3. Go to http://localhost:4242/docs/next/<YOURMARKDOWNFILE_ID> to see your new file locally.

Tips for documenting

  • To add images, save the image in website/static/assets and reference it like this:
![](/assets/admin-dashboard.png "Reaction Dashboard")
  • To link to other articles, reference other articles by their filename:
Refer to the [FAQs](faqs.md) article

  • To enable code syntax highlighting, add js, jsx, graphql, html, sh, git, yaml and more after the ```.

  • For more Markdown features, including autogenerated table of contents, refer to Docusaurus docs.

Sign off your commits

We use the Developer Certificate of Origin (DCO) in lieu of a Contributor License Agreement for all contributions to Reaction Commerce open source projects. We request that contributors agree to the terms of the DCO and indicate that agreement by signing off all commits made to Reaction Commerce projects by adding a line with your name and email address to every Git commit message contributed:

Signed-off-by: Jane Doe [email protected]

You can sign off your commit automatically with Git by using git commit -s if you have your user.name and user.email set as part of your Git configuration.

We ask that you use your real name (please no anonymous contributions or pseudonyms). By signing your commit you are certifying that you have the right to submit it under the open source license used by that particular Reaction Commerce project. You must use your real name (no pseudonyms or anonymous contributions are allowed.)

We use the Probot DCO GitHub app to check for DCO signoffs of every commit.

If you forget to sign off git your commits, the DCO bot will remind you and give you detailed instructions for how to amend your commits to add a signature.

Contributing development

The Header, Footer, index page and version pages are developed in React and CSS within the website/core and website/static directories. Site configuration details are managed in website/siteConfig.js.

Logging

docker-compose up -d && docker-compose logs -f

Linting

docker-compose run --rm web yarn lint
docker-compose run --rm web yarn lint:fix:eslint

Building

docker-compose run --rm web yarn build

Running commands

docker-compose run --rm web [...] will run any command inside a Docker container and then remove the container.

Restart

docker-compose run --rm web yarn install \
&& docker-compose down --rmi local \
&& docker-compose build \
&& docker-compose up

Tests

Tests are stubbed out for now.

Versioning

Add a new version

docker-compose run --rm web yarn run version <version>

Rename an existing version to a new name

docker-compose run --rm web yarn run rename-version <currentVersion> <newVersion>

See Versioning guide for more.

Releasing a new version

  1. Add a new version
docker-compose run --rm web yarn run version <version-number>
  1. Restart the container:
docker-compose down && docker-compose up

  1. Run locally to confirm the version number has been changed in the header on http://localhost:4242, and the previous version has been added to the http://localhost:4242/versions list.

  2. If all things look good, push the branch up to make a pull request.

  3. Merge to trunk to auto-deploy

Deploying

Merge to staging branch

Merging to staging will trigger a CircleCI build to https://reaction-docs-staging.reactioncommerce.com/ using Netlify.

Merge to trunk branch

Merging to trunk will trigger a CircleCI build to https://docs.reactioncommerce.com/ using Netlify.

Algolia search configuration

Search is generously provided by Algolia DocSearch. The configuration for this site's search available here and can be configured by sending a pull request to that repository. More details here.