# st2docs **Repository Path**: aq3cn/st2docs ## Basic Information - **Project Name**: st2docs - **Description**: StackStorm Documentation. - **Primary Language**: Python - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2018-11-06 - **Last Updated**: 2024-12-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README [![StackStorm](https://github.com/stackstorm/st2/raw/master/stackstorm_logo.png)](http://www.stackstorm.com) **StackStorm** is a platform for integration and automation across services and tools, taking actions in response to events. Learn more at [www.stackstorm.com](http://www.stackstorm.com/product). [![Build Status](https://circleci.com/gh/StackStorm/st2docs.png?style=shield)](https://circleci.com/gh/StackStorm/st2docs) # Writing the Docs Product documentation for StackStorm is maintained in this repository. These docs are built using [Sphinx](http://www.sphinx-doc.org/en/stable/). ## Contributing * Fork this repo on GitHub (https://help.github.com/articles/fork-a-repo/). * Make changes to the docs using your favorite editor. * To update docs for the latest - i.e. unstable - release of StackStorm, base your changes off the `master` branch. * To update docs for a released version of StackStorm pick the appropriate version branch (v1.2 etc) and make changes. * Push changes to your fork. * Create a pull request (https://help.github.com/articles/creating-a-pull-request/) against StackStorm/st2docs repository to upstream the changes. * Wait for Travis to complete and one of the StackStorm team shall merge the change. ## Build and Run the Docs. #### Build locally on Linux Follows these steps to build the docs locally: Install the dependencies: For Debian/Ubuntu: ``sudo apt-get install libpython-dev libssl-dev`` For RHEL/CentOS: `` sudo yum install python-devel openssl-devel gcc`` ```bash git clone https://github.com/StackStorm/st2docs.git cd st2docs make docs ``` Keep in mind that the initial ``make docs`` run will take a while because it needs to install all the Python dependencies which are needed to build the docs. `make livedocs` builds the docs and runs the doc site live at [http://localhost:8000](http://localhost:8000) to validate changes locally prior to committing any code. #### Run with Docker ```bash make docker-build make docker-run ``` This will build a docker image and run it in a container, serving docs live at [http://localhost:8000](http://localhost:8000). Edit the sources and enjoy live updates. Before pushing the PR, it's good idea to run a full build and catch any warnings which will fail the official build. Here is how: ``` run --rm -it -v "$PWD"/docs/source:/st2docs/docs/source st2/st2docs /bin/bash -c "make .cleandocs ; make .docs" ``` #### Running docs only To make docs changes, without installing full development environment (e.g., on Mac or Windows): ```bash git clone git@github.com:StackStorm/st2docs.git cd st2docs make docs # make docs will fail; ignore the failure: # it will get st2 and set up virtualenv with sphinx/shinx-autobuild . virtualenv/bin/activate sphinx-autobuild -H 0.0.0.0 -b html ./docs/source/ ./docs/build/html ``` Edit, enjoy live updates. ### For Windows users: 1. Install Docker 2. Run Docker QuickStart Terminal.This way these instructions work as-is (otherwise you will need to convert these instructions to work with a Windows command prompt) 3. cd to docs directory, e.g.: ``` cd /c/Users/stanley/st2docs ``` 4. activate virtualenv: ``` . virtualenv/scripts/activate ``` 5. Run ``` sphinx-autobuild -H 127.0.0.1 -b html ./docs/source/ ./docs/build/html ``` 6. Connect to http://localhost:8000 Edit files. Watch live updates. Enjoy. ## Sphinx Tricks * If the whole section belongs in the Enterprise Edition, put the following note: ``` .. note:: Role Based Access Control (RBAC) is only available in StackStorm Enterprise Edition. For information about enterprise edition and differences between community and enterprise edition, please see `stackstorm.com/product `_. ``` Refer to Enterprise edition in passing with `see Enterprise Edition `_ * TODO (Use [http://localhost:8000/todo.html](http://localhost:8000/todo.html) for full TODO list (must be empty when we ship) : .. todo:: Here is a TODO * Code fragment: .. code-block: bash # List all available triggers st2 trigger list * Reference the document ``` :doc:`/start` :doc:`in the Rules doc ` ``` * Referencing an arbitrary section: for instance, there's examples section in sensors.rst. Define a reference on `examples` section in sensors.rst: .. _sensors-examples: and point to it as from this, or from other documents as: :ref:`sensors-examples` :ref:`My examples ` Note that the leading `_` underscore is gone, and the reference is quoted. Name convention for references is `_filename-refname` (because they are unique across the docs). Note that there is no way to reference just a point in the docs. See http://sphinx-doc.org/markup/inline.html#cross-referencing-syntax * External links: `External link `_ * Inlcude a document, full body: .. include:: /engage.rst * Link to GitHub st2 repo :github_st2:`st2/st2common/st2common/operators.py ` * Link to Github StackStorm-Exchange org: :github_exchange:`Link to a sensu pack repo inside Exchange` * Link to StackStorm Exchange website with a filter query: :web_exchange:`Sensu` * Link to the Exchange website on Github (using a global we set up in source/conf.py) `exchange`_ * The pattern to include an example from `/st2/contrib/examples`: make example file name a reference on github. May say that it is deployed to `/usr/share/doc/st2/examples/`, and auto-include the file: Sample rule: :github_st2:`sample-rule-with-webhook.yaml ` : .. literalinclude:: /../../st2/contrib/examples/rules/sample_rule_with_webhook.yaml :language: json ## Pandoc - convert md <-> rst and more pandoc - a super-tool to convert between formats. Sample for markdown conversion: sudo apt-get install pandoc pandoc --from=markdown --to=rst --output=README.rst README.md ## Misc It's ironic that I use Markdown to write about rST tricks.