zulip/docs/index.rst

.. zulip documentation master file, created by
   sphinx-quickstart on Mon Aug 17 16:24:04 2015.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Zulip documentation!
===============================

Zulip is a powerful, open source group chat application. Written in
Python and using the Django framework, Zulip supports both private
messaging and group chats via conversation streams.

Zulip also supports fast search, drag-and-drop file uploads, image
previews, group private messages, audible notifications, missed-message
emails, desktop apps, and much more.

Further information on the Zulip project and its features can be found
at `https://www.zulip.org <https://www.zulip.org>`__ and in these
docs.  Our code is available at `our GitHub repository
<https://github.com/zulip/>`__.

This set of documents covers installation and contribution instructions.

Contents:

* :ref:`user-docs`
* :ref:`prod-install-docs`
* :ref:`dev-install-docs`
* :ref:`tutorial-docs`
* :ref:`code-docs`
* :ref:`code-testing`
* :ref:`system-docs`

.. _user-docs:

.. toctree::
   :maxdepth: 2
   :caption: Overview

   readme-symlink
   architecture-overview
   directory-structure
   roadmap
   changelog

.. _prod-install-docs:

.. toctree::
   :maxdepth: 2
   :caption: Zulip in production

   prod-requirements
   Installing a production server <prod-install>
   prod-troubleshooting
   prod-customize
   prod-maintain-secure-upgrade
   security-model
   prod-authentication-methods
   prod-postgres

.. _dev-install-docs:

.. toctree::
   :maxdepth: 2
   :caption: Development environment

   Development environment installation <dev-overview>
   Recommended setup (Vagrant) <dev-env-first-time-contributors>
   Advanced setup (non-Vagrant) <dev-setup-non-vagrant>
   Using the development environment <using-dev-environment>
   Developing remotely <dev-remote>

.. _tutorial-docs:

.. toctree::
   :maxdepth: 2
   :caption: Developer tutorials

   integration-guide
   webhook-walkthrough
   new-feature-tutorial
   writing-views
   life-of-a-request
   reading-list

.. _code-docs:

.. toctree::
   :maxdepth: 2
   :caption: Code contribution guide

   git-guide
   version-control
   code-style
   mypy
   code-reviewing
   chat-zulip-org
   zulipbot-usage

.. _code-testing:

.. toctree::
   :maxdepth: 2
   :caption: Code testing

   testing
   linters
   testing-with-node
   testing-with-django
   testing-with-casper
   manual-testing

.. _system-docs:

.. toctree::
   :maxdepth: 2
   :caption: Subsystem documentation

   settings
   events-system
   queuing
   bots-guide
   custom-apps
   pointer
   markdown
   realms
   front-end-build-process
   schema-migrations
   html_css
   hashchange-system
   emoji
   full-text-search
   analytics
   translating
   client
   logging
   release-checklist
   README
   user-docs
Initial sphinx setup from sphinx-quickstart (imported from commit b9fc7a8f2f9352129c104f5dc9305203f2efc63d) 2015-08-18 01:25:12 +02:00			`.. zulip documentation master file, created by`
			`sphinx-quickstart on Mon Aug 17 16:24:04 2015.`
			`You can adapt this file completely to your liking, but it should at least`
			contain the root `toctree` directive.

			`Welcome to Zulip documentation!`
			`===============================`

Rearrange docs table of contents for coherence. The order and structure of the Read The Docs documentation was fairly arbitrary; here's a suggestion for how to change its information architecture so it's more useful to a new contributor. This adds a short Zulip overview, and a table of contents and code contribution intro for new contributors. Fixes: #668. Signed-off-by: Sumana Harihareswara <sumanah@panix.com> 2016-05-14 18:50:19 +02:00			`Zulip is a powerful, open source group chat application. Written in`
			`Python and using the Django framework, Zulip supports both private`
			`messaging and group chats via conversation streams.`

			`Zulip also supports fast search, drag-and-drop file uploads, image`
			`previews, group private messages, audible notifications, missed-message`
			`emails, desktop apps, and much more.`

			`Further information on the Zulip project and its features can be found`
			at `https://www.zulip.org <https://www.zulip.org>`__ and in these
			docs. Our code is available at `our GitHub repository
			<https://github.com/zulip/>`__.

			`This set of documents covers installation and contribution instructions.`

Initial sphinx setup from sphinx-quickstart (imported from commit b9fc7a8f2f9352129c104f5dc9305203f2efc63d) 2015-08-18 01:25:12 +02:00			`Contents:`

docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			* :ref:`user-docs`
Move production installation requirements to separate page. To begin the process of consolidating Zulip documentation on Read the Docs, the requirements are now their own topic page, and index.rst links to it. Fixes: #669. 2016-07-12 21:35:25 +02:00			* :ref:`prod-install-docs`
Move and rearrange developer setup instructions. We aim to consolidate developer documentation on Read The Docs. As a start, this commit turns the first part of README.dev.md into a topic page within /docs/ , and links to it from the doc index. See #669. 2016-07-15 06:51:37 +02:00			* :ref:`dev-install-docs`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			* :ref:`tutorial-docs`
			* :ref:`code-docs`
docs: Extract testing docs to their own TOC section Fixes: #2422. 2016-12-06 12:17:05 +01:00			* :ref:`code-testing`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			* :ref:`system-docs`

			`.. _user-docs:`

Initial sphinx setup from sphinx-quickstart (imported from commit b9fc7a8f2f9352129c104f5dc9305203f2efc63d) 2015-08-18 01:25:12 +02:00			`.. toctree::`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			`:maxdepth: 2`
			`:caption: Overview`
Initial sphinx setup from sphinx-quickstart (imported from commit b9fc7a8f2f9352129c104f5dc9305203f2efc63d) 2015-08-18 01:25:12 +02:00
Rearrange docs table of contents for coherence. The order and structure of the Read The Docs documentation was fairly arbitrary; here's a suggestion for how to change its information architecture so it's more useful to a new contributor. This adds a short Zulip overview, and a table of contents and code contribution intro for new contributors. Fixes: #668. Signed-off-by: Sumana Harihareswara <sumanah@panix.com> 2016-05-14 18:50:19 +02:00			`readme-symlink`
Add architectural overview documentation. Fixes: #453. 2016-05-15 00:01:43 +02:00			`architecture-overview`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			`directory-structure`
			`roadmap`
			`changelog`

Move production installation requirements to separate page. To begin the process of consolidating Zulip documentation on Read the Docs, the requirements are now their own topic page, and index.rst links to it. Fixes: #669. 2016-07-12 21:35:25 +02:00			`.. _prod-install-docs:`

			`.. toctree::`
			`:maxdepth: 2`
			`:caption: Zulip in production`

			`prod-requirements`
docs: Improve installation instruction headings. The previous RTD headings were unclear and resulted in some users attempting to install the Zulip production environment for doing development. This clarifies the situation. 2016-12-07 02:34:41 +01:00			`Installing a production server <prod-install>`
docs: Rename status/debug page to troubleshooting. 2016-08-25 06:40:36 +02:00			`prod-troubleshooting`
Move prod customization guide to new page. 2016-07-12 22:43:00 +02:00			`prod-customize`
Move prod maintenance guide to new page. 2016-07-12 22:52:29 +02:00			`prod-maintain-secure-upgrade`
docs: Extract security-model.md. 2017-01-18 02:43:17 +01:00			`security-model`
docs: Turn SSO auth documentation into general auth page. Also remove this page from the breadcrumb. 2016-07-13 01:05:04 +02:00			`prod-authentication-methods`
Move prod postgres details to separate page. 2016-07-12 23:37:39 +02:00			`prod-postgres`
Move production installation requirements to separate page. To begin the process of consolidating Zulip documentation on Read the Docs, the requirements are now their own topic page, and index.rst links to it. Fixes: #669. 2016-07-12 21:35:25 +02:00
Move and rearrange developer setup instructions. We aim to consolidate developer documentation on Read The Docs. As a start, this commit turns the first part of README.dev.md into a topic page within /docs/ , and links to it from the doc index. See #669. 2016-07-15 06:51:37 +02:00			`.. _dev-install-docs:`

			`.. toctree::`
			`:maxdepth: 2`
docs: Improve installation instruction headings. The previous RTD headings were unclear and resulted in some users attempting to install the Zulip production environment for doing development. This clarifies the situation. 2016-12-07 02:34:41 +01:00			`:caption: Development environment`
Move and rearrange developer setup instructions. We aim to consolidate developer documentation on Read The Docs. As a start, this commit turns the first part of README.dev.md into a topic page within /docs/ , and links to it from the doc index. See #669. 2016-07-15 06:51:37 +02:00
docs: Improve installation instruction headings. The previous RTD headings were unclear and resulted in some users attempting to install the Zulip production environment for doing development. This clarifies the situation. 2016-12-07 02:34:41 +01:00			`Development environment installation <dev-overview>`
docs: Simplify hierarchy of dev setup docs. Based on feedback from first-time contributors, this commit simplifies the number of paths available for finding the dev setup directions you need. Setup instructions are now organized into Recommended (Vagrant) and Advanced (non-Vagrant). In order to get the ToC to display correctly, I've combined all the advanced, non-Vagrant methods into one page. I've left the old pages intact, with a note that the content has been moved and link to the new page. This is in case folks have linked directly to those pages. The advanced setup directions still need to be cleaned up, but this is a start. 2016-11-28 02:50:33 +01:00			`Recommended setup (Vagrant) <dev-env-first-time-contributors>`
			`Advanced setup (non-Vagrant) <dev-setup-non-vagrant>`
docs: Change dev -> development everywhere. 2016-11-29 23:23:54 +01:00			`Using the development environment <using-dev-environment>`
docs: Simplify hierarchy of dev setup docs. Based on feedback from first-time contributors, this commit simplifies the number of paths available for finding the dev setup directions you need. Setup instructions are now organized into Recommended (Vagrant) and Advanced (non-Vagrant). In order to get the ToC to display correctly, I've combined all the advanced, non-Vagrant methods into one page. I've left the old pages intact, with a note that the content has been moved and link to the new page. This is in case folks have linked directly to those pages. The advanced setup directions still need to be cleaned up, but this is a start. 2016-11-28 02:50:33 +01:00			`Developing remotely <dev-remote>`
Move and rearrange developer setup instructions. We aim to consolidate developer documentation on Read The Docs. As a start, this commit turns the first part of README.dev.md into a topic page within /docs/ , and links to it from the doc index. See #669. 2016-07-15 06:51:37 +02:00
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			`.. _tutorial-docs:`

			`.. toctree::`
			`:maxdepth: 2`
			`:caption: Developer tutorials`

Add new markdown documentation to ReadTheDocs. 2016-04-01 23:55:23 +02:00			`integration-guide`
Create new webhook walkthrough page from the integration guide. Breaks out the Hello World example to create a new webhook-walkthrough.md. Includes minor edits so the two docs read well. Adds the new page, "Webhook walkthrough", to the TOC. Fixes #3498 2017-02-06 22:07:45 +01:00			`webhook-walkthrough`
Add new feature tutorial. (imported from commit 1577c2567232aba1a1f1c6d1df83370acf54af55) 2015-08-22 02:05:06 +02:00			`new-feature-tutorial`
Add extensive views writing documentation. [section on REQ substantially expanded by tabbott] Fixes: #880. 2016-07-16 03:13:57 +02:00			`writing-views`
Add Life of a Request doc (#1302) This doc follows the different layers that Zulip uses to handle a request, detailing parts of those layers that would be most commonly interesting to developers. 2016-07-21 01:58:19 +02:00			`life-of-a-request`
docs: Add the Reading list. 2017-01-10 18:40:25 +01:00			`reading-list`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00
			`.. _code-docs:`

			`.. toctree::`
			`:maxdepth: 2`
			`:caption: Code contribution guide`

docs: Add Git and GitHub Guide. Fixes #783, #1754. 2016-09-20 21:40:31 +02:00			`git-guide`
docs: Split out version control guidelines. 2016-06-26 18:57:27 +02:00			`version-control`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			`code-style`
			`mypy`
docs: Add an initial code review document. A first pass at a code review guide. Mostly Tim's draft; I added polish and links. Fixes: #758. 2016-10-19 10:26:51 +02:00			`code-reviewing`
docs: Document chat.zulip.org. 2017-02-12 22:50:11 +01:00			`chat-zulip-org`
docs: Document zulipbot and its usage. Tweaked by tabbott to document why we need it. Fixes #3771 2017-03-04 23:22:44 +01:00			`zulipbot-usage`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00
docs: Extract testing docs to their own TOC section Fixes: #2422. 2016-12-06 12:17:05 +01:00			`.. _code-testing:`

			`.. toctree::`
			`:maxdepth: 2`
			`:caption: Code testing`

			`testing`
			`linters`
			`testing-with-node`
			`testing-with-django`
			`testing-with-casper`
			`manual-testing`

docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			`.. _system-docs:`

			`.. toctree::`
			`:maxdepth: 2`
			`:caption: Subsystem documentation`

			`settings`
docs: Add a long document explaining the events system. This is probably one of Zulip's most important systems, and thus worth documenting carefully. 2017-02-10 10:09:31 +01:00			`events-system`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			`queuing`
Rename and reorder the bots guide 2016-12-20 20:16:02 +01:00			`bots-guide`
docs: Add "Custom Apps" to "Subsystem Documentation". 2016-08-27 17:39:27 +02:00			`custom-apps`
doc: Add pointer and unread counts guide. Tim's comments in #789 are useful to developers in explaining message selection at browser load, narrow, etc. 2016-08-11 22:14:22 +02:00			`pointer`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			`markdown`
docs: Add subsystem section discussing realms and subdomains. 2016-10-31 18:13:56 +01:00			`realms`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			`front-end-build-process`
			`schema-migrations`
docs: Add documentation on HTML and CSS. 2016-06-27 01:03:56 +02:00			`html_css`
docs: Document the frontend hashchange system. 2017-03-22 23:16:46 +01:00			`hashchange-system`
docs: Add initial documentation on the emoji system. 2017-01-29 21:15:29 +01:00			`emoji`
docs: Add some full-text search documentation. 2016-06-26 18:32:54 +02:00			`full-text-search`
developer docs: Add doc for analytics subsystem. 2017-02-22 21:49:29 +01:00			`analytics`
Add documentation on translating Zulip. 2016-04-29 06:55:09 +02:00			`translating`
docs: Document zerver.models.Client's usage for analytics and webhooks. 2017-05-02 03:54:36 +02:00			`client`
docs: Reorganize RTD table of contents. 2016-06-17 02:59:41 +02:00			`logging`
docs: Add a brief release checklist. 2016-11-04 18:50:15 +01:00			`release-checklist`
docs: Add link to documentation building docs. 2016-06-26 19:00:02 +02:00			`README`
docs: Rewrite user documentation styling guide. 2017-01-16 21:38:07 +01:00			`user-docs`