{"id":19601491,"url":"https://github.com/stackstorm/st2docs","last_synced_at":"2025-05-16T13:05:27.915Z","repository":{"id":3331111,"uuid":"49105003","full_name":"StackStorm/st2docs","owner":"StackStorm","description":"StackStorm Documentation.","archived":false,"fork":false,"pushed_at":"2024-12-09T04:11:20.000Z","size":9670,"stargazers_count":66,"open_issues_count":43,"forks_count":174,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-04-03T08:11:54.778Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.stackstorm.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StackStorm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"community_bridge":"stackstorm"}},"created_at":"2016-01-06T01:54:55.000Z","updated_at":"2025-02-20T08:05:17.000Z","dependencies_parsed_at":"2023-01-11T16:16:39.462Z","dependency_job_id":"f203d91d-995e-493e-8f90-bf9ace87dd5d","html_url":"https://github.com/StackStorm/st2docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackStorm%2Fst2docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackStorm%2Fst2docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackStorm%2Fst2docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackStorm%2Fst2docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StackStorm","download_url":"https://codeload.github.com/StackStorm/st2docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248525573,"owners_count":21118700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T09:18:37.850Z","updated_at":"2025-04-12T06:20:24.166Z","avatar_url":"https://github.com/StackStorm.png","language":"Python","readme":"[![StackStorm](https://github.com/stackstorm/st2/raw/master/stackstorm_logo.png)](http://www.stackstorm.com)\n\n**StackStorm** is a platform for integration and automation across services and tools, taking\nactions in response to events. Learn more at [www.stackstorm.com](http://www.stackstorm.com/product).\n\n[![Build Status](https://circleci.com/gh/StackStorm/st2docs.png?style=shield)](https://circleci.com/gh/StackStorm/st2docs)\n\n# Writing the Docs\n\nProduct documentation for StackStorm is maintained in this repository. These docs are built using\n[Sphinx](http://www.sphinx-doc.org/en/stable/).\n\n## Contributing\n\n* Fork this repo on GitHub (https://help.github.com/articles/fork-a-repo/).\n* Make changes to the docs using your favorite editor.\n* To update docs for the latest - i.e. unstable - release of StackStorm, base your changes off the `master` branch.\n* To update docs for a released version of StackStorm pick the appropriate version branch (v1.2 etc) and make changes.\n* Push changes to your fork.\n* Create a pull request (https://help.github.com/articles/creating-a-pull-request/) against StackStorm/st2docs repository\n  to upstream the changes.\n* Wait for Travis to complete and one of the StackStorm team shall merge the change.\n\n## Build and Run the Docs.\n\n#### Build locally on Linux\nFollows these steps to build the docs locally:\n\nInstall the dependencies:\n\nFor Debian/Ubuntu: ``sudo apt-get install python-dev libssl-dev libldap2-dev libsasl2-dev ldap-utils``\n\nFor RHEL/CentOS: `` sudo dnf install python2-devel python3-devel openldap-devel``\n\n```bash\ngit clone https://github.com/StackStorm/st2docs.git\ncd st2docs\nmake docs\n```\n\nKeep in mind that the initial ``make docs`` run will take a while because it needs to install\nall the Python dependencies which are needed to build the docs.\n\n`make livedocs` builds the docs and runs the doc site live at [http://localhost:8000](http://localhost:8000) to\nvalidate changes locally prior to committing any code.\n\n#### Run with Docker\n```bash\nmake docker-build\nmake docker-run\n```\nThis will build a docker image and run it in a container, serving docs live at [http://localhost:8000](http://localhost:8000).\nEdit the sources and enjoy live updates.\n\nBefore 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:\n```\nrun --rm -it -v \"$PWD\"/docs/source:/st2docs/docs/source st2/st2docs /bin/bash -c \"make .cleandocs ; make .docs\"\n```\n#### Running docs only\n\nTo make docs changes, without installing full development environment (e.g., on Mac or Windows):\n\n```bash\ngit clone git@github.com:StackStorm/st2docs.git\ncd st2docs\nmake docs\n# make docs will fail; ignore the failure:\n# it will get st2 and set up virtualenv with sphinx/shinx-autobuild\n. virtualenv/bin/activate\nsphinx-autobuild -H 0.0.0.0 -b html ./docs/source/ ./docs/build/html\n```\n\nEdit, enjoy live updates.\n\n### For Windows users:\n\n1. Install Docker\n\n2. Run Docker QuickStart Terminal.This way these instructions work as-is (otherwise you will need\n   to convert these instructions to work with a Windows command prompt)\n\n3. cd to docs directory, e.g.:\n   ```bash\n   cd /c/Users/stanley/st2docs\n   ```\n4. activate virtualenv:\n   ```bash\n   . virtualenv/scripts/activate\n   ```\n5. Run\n   ```bash\n   sphinx-autobuild -H 127.0.0.1 -b html ./docs/source/ ./docs/build/html\n   ```\n6. Connect to http://localhost:8000 Edit files. Watch live updates. Enjoy.\n\n## Sphinx Tricks\n\n* TODO (Use [http://localhost:8000/todo.html](http://localhost:8000/todo.html) for full TODO list (must be empty when we ship):\n\n  ```rst\n  .. todo:: Here is a TODO\n  ```\n\n* Code fragment:\n\n  ```rst\n  .. code-block:: bash\n\n      # List all available triggers\n      st2 trigger list\n  ```\n\n* Reference the document\n\n  ```rst\n  :doc:`/start`\n  :doc:`in the Rules doc \u003c/rules\u003e`\n  ```\n* Referencing an arbitrary section: for instance, there's examples section in `sensors.rst`. Define a reference on `examples` section in `sensors.rst`:\n\n  ```rst\n  .. _sensors-examples:\n  ```\n\n  and point to it as from this, or from other documents as:\n\n  ```rst\n  :ref:`sensors-examples`\n  :ref:`My examples \u003csensors-examples\u003e`\n  ```\n\n  Note that the leading `_` underscore is gone, and the reference is quoted.\n\n  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\n\n* External links:\n\n  ```rst\n  `External link \u003chttp://webchat.freenode.net/?channels=stackstorm\u003e`_\n  ```\n\n* Include a document, full body:\n\n  ```rst\n  .. include:: /engage.rst\n  ```\n\n* Link to GitHub st2 repo\n\n  ```rst\n  :github_st2:`st2/st2common/st2common/operators.py \u003c/st2common/st2common/operators.py\u003e`\n  ```\n\n* Link to Github StackStorm-Exchange org:\n\n  ```rst\n  :github_exchange:`Link to a sensu pack repo inside Exchange\u003cstackstorm-sensu\u003e`\n  ```\n\n* Link to StackStorm Exchange website with a filter query:\n\n  ```rst\n  :web_exchange:`Sensu\u003csensu\u003e`\n  ```\n\n* Link to the Exchange website on Github (using a global we set up in source/conf.py)\n\n  ```rst\n  `exchange`_\n  ```\n\n* 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:\n\n  ```rst\n  Sample rule: :github_st2:`sample-rule-with-webhook.yaml\n  \u003c/contrib/examples/rules/sample-rule-with-webhook.yaml\u003e` :\n\n  .. literalinclude:: /../../st2/contrib/examples/rules/sample_rule_with_webhook.yaml\n      :language: json\n  ```\n\n## Pandoc - convert md \u003c-\u003e rst and more\n\npandoc - a super-tool to convert between formats. Sample for markdown conversion:\n\n```bash\nsudo apt-get install pandoc\npandoc --from=markdown --to=rst --output=README.rst README.md\n```\n\n## Misc\n\nIt's ironic that I use Markdown to write about rST tricks.\n","funding_links":["https://funding.communitybridge.org/projects/stackstorm"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackstorm%2Fst2docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackstorm%2Fst2docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackstorm%2Fst2docs/lists"}