Code Monkey home page Code Monkey logo

sentry-docs's Introduction

Federated Sentry Documentation

This repository contains the documentation for docs.sentry.io and some support to build the entire documentation which in parts is made from content of other repositories.

Understanding the Structure

The structure of this repository is broken into a few separate parts:

  • build/: this folder contains the final build artifacts. At present only two builds are supported: html and dirhtml. They however use custom builders called sentryhtml and sentrydirhtml. For more information have a look into the Makefile.
  • doc-modules/: this folder contains references to the submodules for the individual split docs. The docs/clients folder contains a bunch of symlinks that point to the appropriate place within the SDK doc folder for instance.
  • design/: this folder contains the JavaScript, CSS files and templates as well as some webpack related stuff for the final design of the documentation.
  • doc-support: this submodule references the sentry-doc-support repository which contains support for building federated docs. See below for more information.

Building the Docs

The point of the federated documentation system is that a whole cohesive documentation can be built however the individual documentation for the components can remain in the individual repositories.

For building the required environment, you can use this command:

make requirements

For building the complete docs, you can use this command:

make build

To clean the build use this:

make clean

At this point you'll need a real webserver to serve the docs otherwise various browser security controls will block some of our JavaScript:

bin/web

If you only need to rebuild pages in the sentry-docs repo (and not the SDK repo docs), you can use this command:

make fast-build

How the Docs Build

The building of the docs out of this repository is controlled by two environment variables:

SENTRY_FEDERATED_DOCS=1:
This is exported for all documentation builds from this repository directly. It indicates that the documentation is build for the federation use case and can be picked up by individual client configs to change behavior.
SENTRY_DOC_VARIANT:
This is set to either hosted or self to indicate which flavor of sentry docs to build. Within the docs the sentry:edition directive can be used to filter the docs.

Customizing Docs

To include or exclude parts of the documentation the sentry:edition directive comes in useful:

.. sentry:edition:: self:
This only builds when the docs are built through the non federated build.
.. sentry:edition:: hosted:
Only included if the docs are build for the hosted (getsentry.com) docs

Multiple variants can be defined with a comma.

Doc Sync Hook

This repository has a helpful bot that listens to a webhook that can be used to update the cross references on commits automatically. The hook is available at https://sentry-doc-hook.herokuapp.com/. It can be registered on any github repository that is referenced as a submodule here. By default it only tracks the master branch and changes below /docs.

To override the branch you can pass ?branches= as parameter which is a comma separated list of branches. To override the tracked paths provide ?prefixes= which is a comma seperated list of path prefixes.

sentry-docs's People

Contributors

benvinegar avatar bobrik avatar bretthoerner avatar cameronmcefee avatar chadwhitacre avatar ckj avatar dcramer avatar ehfeng avatar hazat avatar jessla avatar jtcunning avatar kstenerud avatar lewisjellis avatar macqueen avatar mattrobenolt avatar mdamien avatar meredithanya avatar mitsuhiko avatar nate-opti avatar nateberkopec avatar timsavage avatar tkaemming avatar torarnv avatar travisoneill avatar wong2 avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.