zulip/docs
Eeshan Garg 8ad3a8bc9a integration-guide: Replace references to old-style fixture directories.
The integration guide has now been updated to reflect the recent
decision to store webhook fixtures in
zerver/webhooks/<webhook_name>/fixtures/ as opposed to
zerver/fixtures/<webhook_name>/.
2017-04-28 11:07:03 -07:00
..
_static css: Enforce one selector per line. 2017-03-26 16:57:33 -07:00
images docs: Rewrite user documentation styling guide. 2017-01-16 22:15:01 -08:00
.gitignore Initial sphinx setup from sphinx-quickstart 2015-08-18 17:31:32 -07:00
Makefile Initial sphinx setup from sphinx-quickstart 2015-08-18 17:31:32 -07:00
README.md dev: Expose coverage and built documentation to web. 2017-03-23 13:10:06 -07:00
THIRDPARTY docs: Update code of conduct. 2017-04-15 16:53:04 -07:00
analytics.md analytics: Refactor legacy 'zulip_internal' decorator. 2017-04-22 11:42:02 -07:00
architecture-overview.md glossary: Add a few comment useful terms. 2017-03-22 15:49:20 -07:00
bots-guide.md doc updates: Remove triage_message function from contrib-bots. 2017-03-07 22:23:11 -08:00
brief-install-vagrant-dev.md Fix grammatical and spelling errors in Zulip/docs. 2017-01-16 20:16:12 -08:00
changelog.md Add release notes from Zulip Server 1.5.1. 2017-02-07 11:40:49 -08:00
chat-zulip-org.md chat-zulip-org: Document learning stream. 2017-04-20 16:04:42 -07:00
chinese.md Fix grammatical and spelling errors in Zulip/docs. 2017-01-16 20:16:12 -08:00
code-of-conduct.md docs: Update code of conduct. 2017-04-15 16:53:04 -07:00
code-reviewing.md docs: Add a resource to code review doc. 2017-02-14 11:32:01 +01:00
code-style.md Rename tools/lint-all to tools/lint. 2017-04-21 14:57:47 -07:00
conf.py lint: Clean up E123 PEP-8 rule. 2017-01-23 21:34:26 -08:00
conversion.md models: Rename RealmAlias model to RealmDomain. 2017-04-04 15:48:03 -07:00
custom-apps.md docs: Fix broken URL. 2017-01-22 13:04:37 -08:00
dev-env-first-time-contributors.md docs: Fix minor link formatting. 2017-03-19 09:16:06 -07:00
dev-overview.md Fix grammatical and spelling errors in Zulip/docs. 2017-01-16 20:16:12 -08:00
dev-remote.md Fix grammatical and spelling errors in Zulip/docs. 2017-01-16 20:16:12 -08:00
dev-setup-non-vagrant.md docs: Update Docker development instructions to include chown. 2017-04-24 21:40:44 -07:00
directory-structure.md Update integration-guide according to integrations redesign. 2017-01-26 12:27:38 -08:00
emoji.md docs: Add initial documentation on the emoji system. 2017-01-29 12:15:29 -08:00
events-system.md docs: Fix typos in events-system.md. 2017-03-07 19:46:16 -08:00
front-end-build-process.md docs: Extend discussion of package.json. 2017-03-07 16:39:50 -08:00
full-text-search.md docs: Fix markup issue in pgroonga docs. 2017-02-08 10:17:23 -08:00
german.md docs: Fix link to formal/information in German guide. 2017-02-12 16:46:53 -08:00
git-guide.md docs: Tweak reset-to-pull-request warning. 2017-04-21 10:12:04 -07:00
hashchange-system.md docs: hashchange-system: add more detail and fix some sentences. 2017-03-23 15:15:44 -07:00
html_css.md Rename "Administration" to "Organization" in the settings UI. 2017-04-07 17:32:56 -07:00
html_unescape.py Change shebangs from python2.7 to python. 2016-05-29 05:03:08 -07:00
index.rst docs: Document the frontend hashchange system. 2017-03-22 15:21:36 -07:00
install-docker-dev.md docs: Simplify hierarchy of dev setup docs. 2016-11-29 14:13:09 -08:00
install-generic-unix-dev.md docs: Simplify hierarchy of dev setup docs. 2016-11-29 14:13:09 -08:00
install-ubuntu-without-vagrant-dev.md docs: Simplify hierarchy of dev setup docs. 2016-11-29 14:13:09 -08:00
integration-guide.md integration-guide: Replace references to old-style fixture directories. 2017-04-28 11:07:03 -07:00
life-of-a-request.md docs: Add a long document explaining the events system. 2017-02-10 01:17:15 -08:00
linters.md Rename tools/lint-all to tools/lint. 2017-04-21 14:57:47 -07:00
logging.md Improve first-time contributor docs. 2016-05-31 07:47:45 -07:00
manual-testing.md compose: Rename 'New stream message' to 'New topic'. 2017-03-01 21:31:43 -08:00
markdown.md docs: tweak markdown manual testing docs a bit. 2017-02-16 16:24:12 -08:00
migration-renumbering.md docs: Update docs to include `renumber-migrations` tool. 2017-04-17 20:53:35 -07:00
mypy.md mypy: Update docs to recommend typing.Text instead of six.text_type. 2016-12-26 16:11:37 -08:00
new-feature-tutorial.md Documentation: Improve new feature tutorial. 2017-04-26 16:19:51 -07:00
pointer.md unread: Add tool for marking all messages as unread for testing. 2017-04-25 15:40:12 -07:00
polish.md docs: Wrap long lines in translation guides. 2017-01-05 14:08:42 -08:00
prod-authentication-methods.md docs: Fix style in authentication methods doc. 2016-10-22 20:14:56 -07:00
prod-customize.md Add default response for `terms` and `privacy` endpoints. 2017-04-12 14:09:14 -07:00
prod-email.md docs: Update email configuration documentation. 2017-02-22 22:26:43 -08:00
prod-install.md Rename "Administration" to "Organization" in the settings UI. 2017-04-07 17:32:56 -07:00
prod-maintain-secure-upgrade.md Update prod-maintain-secure-upgrade.md 2017-04-25 15:25:22 -07:00
prod-postgres.md lint: Check for long lines in all markdown files in general. 2017-01-05 15:06:34 -08:00
prod-requirements.md prod-requirements.md: Fix grammar. 2017-04-11 22:30:02 -07:00
prod-troubleshooting.md Explain Django "Invalid HTTP_HOST header" log message. 2017-02-27 00:13:32 -08:00
queuing.md queues: Add new system for managing rabbitmq per-queue work. 2017-02-19 16:18:37 -08:00
reading-list.md docs: Add book about OSS prod to the reading list. 2017-01-30 11:32:23 -08:00
readme-symlink.md Rearrange docs table of contents for coherence. 2016-05-31 09:07:09 -07:00
realms.md Fix grammatical and spelling errors in Zulip/docs. 2017-01-16 20:16:12 -08:00
release-checklist.md docs: Update release checklist to mention GitHub. 2017-02-01 09:48:00 -08:00
requirements.readthedocs.txt Move doc building dependencies to requirements/docs.txt. 2016-06-20 16:05:42 -07:00
roadmap.md roadmap: Mark a bunch of projects as completed. 2017-02-07 10:12:01 -08:00
russian.md docs: Wrap long lines in Russian style guide. 2017-01-05 14:31:34 -08:00
schema-migrations.md docs: Update docs to include `renumber-migrations` tool. 2017-04-17 20:53:35 -07:00
security-model.md Rename "Administration" to "Organization" in the settings UI. 2017-04-07 17:32:56 -07:00
settings.md Rename "Administration" to "Organization" in the settings UI. 2017-04-07 17:32:56 -07:00
spanish.md docs: Improve Spanish style guide. 2017-01-28 19:08:14 -08:00
ssl-certificates.md docs: Move SSL docs to a dedicated page. 2016-08-25 09:37:33 -07:00
testing-with-casper.md Rename "Administration" to "Organization" in the settings UI. 2017-04-07 17:32:56 -07:00
testing-with-django.md Add option for re-running failed tests. 2017-04-12 11:35:31 -07:00
testing-with-node.md tools: Convert test-js-with-node to Python. 2017-04-05 12:02:49 -07:00
testing.md Rename tools/lint-all to tools/lint. 2017-04-21 14:57:47 -07:00
translating.md Rename tools/lint-all to tools/lint. 2017-04-21 14:57:47 -07:00
user-docs.md Rename "Administration" to "Organization" in the settings UI. 2017-04-07 17:32:56 -07:00
users.md Add draft document for user populations. 2016-11-08 15:28:04 -08:00
using-dev-environment.md Remove some some duplicate words in copy. 2017-01-23 23:15:04 -08:00
version-control.md docs: Add explanation on small fixes in PRs. 2017-03-27 14:44:33 -07:00
webhook-walkthrough.md webhook-walkthrough: Replace references to old-style fixture directories. 2017-04-28 11:07:03 -07:00
writing-views.md Add ui_report shim. 2017-03-19 11:05:44 -07:00
zulipbot-usage.md docs: Update zulipbot guide with new features. 2017-03-15 18:01:23 -07:00

README.md

Documentation

Zulip has three major documentation systems:

  • Developer and sysadmin documentation: Documentation for people actually interacting with the Zulip codebase (either by developing it or installing it), and written in Markdown.

  • Core website documentation: Complete webpages for complex topics, written in HTML, JavaScript, and CSS (using the Django templating system). These roughly correspond to the documentation someone might look at when deciding whether to use Zulip. We don't expect to ever have more than about 10 pages written using this system.

  • General user documentation: Our scalable system for documenting Zulip's huge collection of specific features without a lot of overhead or duplicated code/syntax, written in Markdown. We expect to eventually have around 100 pages written using this system. The target audience for this system is individual Zulip users.

These three systems are documented in detail.

Developer and sysadmin documentation

What you are reading right now is part of the collection of documentation targeted at developers and people running their own Zulip servers. These docs are written in Commonmark Markdown with a small bit of rST. We've chosen Markdown because it is easy to write. The source for Zulip's developer documentation is at docs/ in the Zulip git repository, and they are served in production at zulip.readthedocs.io.

If you want to build the developer documentation locally (e.g. to test your changes), the dependencies are automatically installed as part of Zulip development environment provisioning, and you can build the documentation using:

cd docs/
make html

and then opening http://127.0.0.1:9991/docs/index.html in your browser. The raw files are available at file:///path/to/zulip/docs/_build/html/index.html in your browser (so you can also use e.g. firefox docs/_build/html/index.html from the root of your Zulip checkout).

If you are adding a new page to the table of contents, you will want to modify docs/index.rst and run make clean before make html, so that other docs besides your new one also get the new entry in the table of contents.

You can also usually test your changes by pushing a branch to GitHub and looking at the content on the GitHub web UI, since GitHub renders Markdown, though that won't be as faithful as the make html approach.

When editing dependencies for the Zulip documentation, you should edit requirements/docs.txt (which is used by ReadTheDocs to build the Zulip developer documentation, without installing all of Zulip's dependencies).

Core website documentation

Zulip has around 10 HTML documentation pages under templates/zerver for specific major topics, like the features list, client apps, integrations, hotkeys, API bindings, etc. These documents often have somewhat complex HTML and JavaScript, without a great deal of common pattern between them other than inheriting from the portico.html template. We generally avoid adding new pages to this collection unless there's a good reason, but we don't intend to migrate them, either, since this system gives us the flexibility to express these important elements of the product clearly.

General user documentation

To learn more about Zulip's general user documentation, visit our guide on writing user documentation here.