Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Reorganize developer docs to improve navigation. 

This commit helps reduce clutter on the navigation sidebar.
Creates new directories and moves relevant files into them.
Modifies index.rst, symlinks, and image paths accordingly.

This commit also enables expandable/collapsible navigation items,
renames files in docs/development and docs/production,
modifies /tools/test-documentation so that it overrides a theme setting,
Also updates links to other docs, file paths in the codebase that point
to developer documents, and files that should be excluded from lint tests.

Note that this commit does not update direct links to
zulip.readthedocs.io in the codebase; those will be resolved in an
upcoming follow-up commit (it'll be easier to verify all the links
once this is merged and ReadTheDocs is updated).

Fixes #5265.
This commit is contained in:
David Rosa Tamsen 2017-11-08 10:55:36 -06:00 committed by Tim Abbott
parent 3b95a6d2d9
commit 7072fa5b37
123 changed files with 450 additions and 386 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/brief-install-vagrant-dev.md
View File

@ -71,7 +71,7 @@ lint, management commands, etc., use `vagrant ssh`.
At this point you should [read about using the development At this point you should [read about using the development
environment][using-dev]. environment][using-dev].
[using-dev]: using-dev-environment.html [using-dev]: using.html
### Specifying a proxy ### Specifying a proxy

2
docs/conf.py
View File

@ -118,7 +118,7 @@ if not on_rtd:
# further. For a list of options available for each theme, see the # further. For a list of options available for each theme, see the
# documentation. # documentation.
html_theme_options = { html_theme_options = {
'sticky_navigation': False, 'collapse_navigation': False,
} }
# Add any paths that contain custom themes here, relative to this directory. # Add any paths that contain custom themes here, relative to this directory.

1
docs/contributing.md
View File

@ -1 +0,0 @@
../CONTRIBUTING.md

0
docs/accessibility.md → docs/contributing/accessibility.md
View File

0
docs/bug-reports.md → docs/contributing/bug-reports.md
View File

2
docs/chat-zulip-org.md → docs/contributing/chat-zulip-org.md
View File

@ -32,7 +32,7 @@ minutes to a few hours, depending on the time of day.
[gender-neutral language](https://en.wikipedia.org/wiki/Gender-neutral_language). [gender-neutral language](https://en.wikipedia.org/wiki/Gender-neutral_language).
For example, avoid using a pronoun like her or his in sentences like For example, avoid using a pronoun like her or his in sentences like
"Every developer should clean [their] keyboard at least once a week." "Every developer should clean [their] keyboard at least once a week."
* Follow the community [code of conduct](code-of-conduct.html). * Follow the community [code of conduct](../code-of-conduct.html).
* Participate! Zulip is a friendly and welcoming community, and we * Participate! Zulip is a friendly and welcoming community, and we
love meeting new people, hearing about what brought them to Zulip, love meeting new people, hearing about what brought them to Zulip,
and getting their feedback. If you're not sure where to start, and getting their feedback. If you're not sure where to start,

16
docs/code-reviewing.md → docs/contributing/code-reviewing.md
View File

@ -103,7 +103,7 @@ this?". Good choices include
change being made. Tests that exclude whole classes of potential change being made. Tests that exclude whole classes of potential
bugs are preferred when possible (e.g., the common test suite bugs are preferred when possible (e.g., the common test suite
`test_bugdown.py` between the Zulip server's [frontend and backend `test_bugdown.py` between the Zulip server's [frontend and backend
Markdown processors](markdown.html), or the `GetEventsTest` test for Markdown processors](../subsystems/markdown.html), or the `GetEventsTest` test for
buggy race condition handling). buggy race condition handling).
* *Translation.* Make sure that the strings are marked for * *Translation.* Make sure that the strings are marked for
@ -192,11 +192,11 @@ We also strongly recommend reviewers to go through the following resources.
* [Code Review - A consolidation of advice and stuff from the * [Code Review - A consolidation of advice and stuff from the
sinternet](https://gist.github.com/porterjamesj/002fb27dd70df003646df46f15e898de) sinternet](https://gist.github.com/porterjamesj/002fb27dd70df003646df46f15e898de)
article by James J. Porter article by James J. Porter
* [Zulip Code of Conduct](https://zulip.readthedocs.io/en/latest/code-of-conduct.html) * [Zulip Code of Conduct](../code-of-conduct.html)
[code-style]: code-style.html [code-style]: ../contributing/code-style.html
[commit-messages]: version-control.html#commit-messages [commit-messages]: ../contributing/version-control.html#commit-messages
[test-writing]: testing.html [test-writing]: ../testing/testing.html
[mypy]: mypy.html [mypy]: ../contributing/mypy.html
[git tool]: git-guide.html#fetch-a-pull-request-and-rebase [git tool]: ../contributing/git-guide.html#fetch-a-pull-request-and-rebase
[translation]: translating.html [translation]: ../translating/translating.html

4
docs/code-style.md → docs/contributing/code-style.md
View File

@ -163,7 +163,7 @@ Don't use it:
### Translation tags ### Translation tags
Remember to Remember to
[tag all user-facing strings for translation](translating.html), whether [tag all user-facing strings for translation](../translating/translating.html), whether
they are in HTML templates or JavaScript editing the HTML (e.g. error they are in HTML templates or JavaScript editing the HTML (e.g. error
messages). messages).
@ -292,5 +292,5 @@ All significant new features should come with tests. See testing.
### Third party code ### Third party code
See [our docs on dependencies](dependencies.html) for discussion of See [our docs on dependencies](../subsystems/dependencies.html) for discussion of
rules about integrating third-party projects. rules about integrating third-party projects.

68
docs/git-guide.md → docs/contributing/git-guide.md
View File

@ -364,7 +364,7 @@ First, sign in to [Travis CI][travis-ci] with your GitHub account and authorize
Travis CI to access your GitHub account and repositories. Once you've done Travis CI to access your GitHub account and repositories. Once you've done
this, Travis CI will fetch your repository information and display it on your this, Travis CI will fetch your repository information and display it on your
[profile page][travis-ci-profile]. From there you can enable integration with [profile page][travis-ci-profile]. From there you can enable integration with
Zulip. ([See screen cast](_static/zulip-travisci.gif).) Zulip. ([See screen cast](../_static/zulip-travisci.gif).)
## Using Git as you work ## Using Git as you work
@ -494,7 +494,7 @@ Now you're ready to work on the issue or feature.
### Run linters and tests locally ### Run linters and tests locally
In addition to having Travis run tests and linters each time you push a new In addition to having Travis run tests and linters each time you push a new
commit, you can also run them locally. See [testing](testing.html) for details. commit, you can also run them locally. See [testing](../testing/testing.html) for details.
### Stage changes ### Stage changes
@ -1513,19 +1513,19 @@ git rebase --continue
[github-help-add-ssh-key]: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/ [github-help-add-ssh-key]: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
[github-help-resolve-merge-conflict]: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ [github-help-resolve-merge-conflict]: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
[github-help-closing-issues]: https://help.github.com/articles/closing-issues-via-commit-messages/ [github-help-closing-issues]: https://help.github.com/articles/closing-issues-via-commit-messages/
[zulip-rtd-version-control]: version-control.html [zulip-rtd-version-control]: ../contributing/version-control.html
[zulip-rtd-commit-messages]: version-control.html#commit-messages [zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages
[zulip-rtd-commit-discipline]: version-control.html#commit-discipline [zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline
[zulip-rtd-lint-tools]: code-style.html#lint-tools [zulip-rtd-lint-tools]: ../contributing/code-style.html#lint-tools
[zulip-rtd-testing]: testing.html [zulip-rtd-testing]: ../testing/testing.html
[zulip-rtd-mypy]: mypy.html [zulip-rtd-mypy]: ../contributing/mypy.html
[zulip-rtd-code-style]: code-style.html [zulip-rtd-code-style]: ../contributing/code-style.html
[zulip-rtd-travis-ci]: travis-ci.html [zulip-rtd-travis-ci]: travis-ci.html
[zulip-rtd-dev-overview]: dev-overview.html [zulip-rtd-dev-overview]: ../development/overview.html
[zulip-rtd-dev-first-time]: dev-env-first-time-contributors.html [zulip-rtd-dev-first-time]: ../development/setup-vagrant.html
[zulip-rtd-zulipbot-usage]: zulipbot-usage.html [zulip-rtd-zulipbot-usage]: zulipbot-usage.html
[gitgui-tower]: https://www.git-tower.com/ [gitgui-tower]: https://www.git-tower.com/
[git-bash-admin]: dev-env-first-time-contributors.html#running-git-bash-as-an-administrator [git-bash-admin]: ../development/setup-vagrant.html#running-git-bash-as-an-administrator
[gitgui-fork]: https://git-fork.com/ [gitgui-fork]: https://git-fork.com/
[gitgui-gitxdev]: https://rowanj.github.io/gitx/ [gitgui-gitxdev]: https://rowanj.github.io/gitx/
[gitgui-ghdesktop]: https://desktop.github.com/ [gitgui-ghdesktop]: https://desktop.github.com/
@ -1538,31 +1538,31 @@ git rebase --continue
[gitgui-gitk]: https://git-scm.com/docs/gitk [gitgui-gitk]: https://git-scm.com/docs/gitk
[travis-ci]: https://travis-ci.org/ [travis-ci]: https://travis-ci.org/
[travis-ci-profile]: https://travis-ci.org/profile [travis-ci-profile]: https://travis-ci.org/profile
[screenshots-gifs]: screenshot-and-gif-software.html [screenshots-gifs]: ../tutorials/screenshot-and-gif-software.html
[self-setup]: git-guide.html#setup-git [self-setup]: ../contributing/git-guide.html#setup-git
[self-how-git-is-different]: git-guide.html#how-git-is-different [self-how-git-is-different]: ../contributing/git-guide.html#how-git-is-different
[self-git-terms]: git-guide.html#important-git-terms [self-git-terms]: ../contributing/git-guide.html#important-git-terms
[self-get-zulip-code]: git-guide.html#get-zulip-code [self-get-zulip-code]: ../contributing/git-guide.html#get-zulip-code
[self-use-git]: git-guide.html#using-git-as-you-work [self-use-git]: ../contributing/git-guide.html#using-git-as-you-work
[self-create-pr]: git-guide.html#create-a-pull-request [self-create-pr]: ../contributing/git-guide.html#create-a-pull-request
[self-update-pr]: git-guide.html#update-a-pull-request [self-update-pr]: ../contributing/git-guide.html#update-a-pull-request
[self-collaborate]: git-guide.html#collaborate [self-collaborate]: ../contributing/git-guide.html#collaborate
[self-review-changes]: git-guide.html#review-changes [self-review-changes]: ../contributing/git-guide.html#review-changes
[self-trouble]: git-guide.html#get-and-stay-out-of-trouble [self-trouble]: ../contributing/git-guide.html#get-and-stay-out-of-trouble
[self-zulip-tools]: git-guide.html#zulip-specific-tools [self-zulip-tools]: ../contributing/git-guide.html#zulip-specific-tools
[self-clone-to-your-machine]: git-guide.html#step-1b-clone-to-your-machine [self-clone-to-your-machine]: ../contributing/git-guide.html#step-1b-clone-to-your-machine
[self-connect-upstream]: git-guide.html#step-1c-connect-your-fork-to-zulip-upstream [self-connect-upstream]: ../contributing/git-guide.html#step-1c-connect-your-fork-to-zulip-upstream
[self-keep-up-to-date]: git-guide.html#keep-your-fork-up-to-date [self-keep-up-to-date]: ../contributing/git-guide.html#keep-your-fork-up-to-date
[self-fetch-another-branch]: git-guide.html#fetch-another-contributor-s-branch [self-fetch-another-branch]: ../contributing/git-guide.html#fetch-another-contributor-s-branch
[self-fetch-pr]: git-guide.html#checkout-a-pull-request-locally [self-fetch-pr]: ../contributing/git-guide.html#checkout-a-pull-request-locally
[self-push-commits]: git-guide.html#push-your-commits-to-github [self-push-commits]: ../contributing/git-guide.html#push-your-commits-to-github
[self-travisci]: git-guide.html#step-3-configure-travis-ci-continuous-integration [self-travisci]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration
[self-multiple-computers]: git-guide.html#working-from-multiple-computers [self-multiple-computers]: ../contributing/git-guide.html#working-from-multiple-computers
[self-git-terms]: git-guide.html#important-git-terms [self-git-terms]: ../contributing/git-guide.html#important-git-terms
[tools-PR]: #fetch-a-pull-request-and-rebase [tools-PR]: #fetch-a-pull-request-and-rebase
[images-gui-stage]: _images/zulip-gui-stage.gif [images-gui-stage]: _images/zulip-gui-stage.gif
[images-gui-hist]: _images/zulip-gui-hist-tower.png [images-gui-hist]: _images/zulip-gui-hist-tower.png
[images-create-pr]: images/zulip-open-pr.png [images-create-pr]: ../images/zulip-open-pr.png
[understanding-git]: http://web.mit.edu/nelhage/Public/git-slides-2009.pdf [understanding-git]: http://web.mit.edu/nelhage/Public/git-slides-2009.pdf
[edx-howto-rebase-pr]: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request [edx-howto-rebase-pr]: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request
[tig]: http://jonas.nitro.dk/tig/ [tig]: http://jonas.nitro.dk/tig/

16
docs/contributing/index.rst Normal file
View File

@ -0,0 +1,16 @@
#######################
Code Contribution Guide
#######################
.. toctree::
:maxdepth: 3
git-guide
version-control
code-style
mypy
code-reviewing
chat-zulip-org
zulipbot-usage
accessibility
bug-reports

0
docs/mypy.md → docs/contributing/mypy.md
View File

0
docs/version-control.md → docs/contributing/version-control.md
View File

0
docs/zulipbot-usage.md → docs/contributing/zulipbot-usage.md
View File

12
docs/development/index.rst Normal file
View File

@ -0,0 +1,12 @@
#######################
Development Environment
#######################
.. toctree::
:maxdepth: 3
Development environment installation <overview>
Recommended setup (Vagrant) <setup-vagrant>
Advanced Setup (non-Vagrant) <setup-advanced>
Using the development environment <using>
Developing remotely <remote>

18
docs/dev-overview.md → docs/development/overview.md
View File

@ -82,14 +82,14 @@ And if you've setup the Zulip development environment on a remote
machine, take a look at our tips for machine, take a look at our tips for
[developing remotely][dev-remote]. [developing remotely][dev-remote].
[dev-remote]: dev-remote.html [dev-remote]: remote.html
[install-direct]: dev-setup-non-vagrant.html#installing-directly-on-ubuntu [install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu
[install-docker]: dev-setup-non-vagrant.html#using-docker-experimental [install-docker]: ../development/setup-advanced.html#using-docker-experimental
[install-generic]: dev-setup-non-vagrant.html#installing-manually-on-linux [install-generic]: ../development/setup-advanced.html#installing-manually-on-linux
[install-vagrant]: dev-env-first-time-contributors.html [install-vagrant]: ../development/setup-vagrant.html
[self-install-remote]: #installing-remotely [self-install-remote]: #installing-remotely
[self-slow-internet]: #slow-internet-connections [self-slow-internet]: #slow-internet-connections
[configure-proxy]: dev-env-first-time-contributors.html#specifying-a-proxy [configure-proxy]: ../development/setup-vagrant.html#specifying-a-proxy
[using-dev-env]: using-dev-environment.html [using-dev-env]: using.html
[testing]: testing.html [testing]: ../testing/testing.html
[travis-ci]: git-guide.html#step-3-configure-travis-ci-continuous-integration [travis-ci]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration

20
docs/dev-remote.md → docs/development/remote.md
View File

@ -56,7 +56,7 @@ navigate to `http://<REMOTE_IP>:9991` and you should see something like
this screenshot of the Zulip development environment: this screenshot of the Zulip development environment:
![Image of Zulip development ![Image of Zulip development
environment](images/zulip-dev.png) environment](../images/zulip-dev.png)
You can [port You can [port
forward](https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding) using forward](https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding) using
@ -87,7 +87,7 @@ don't have a favorite, here are some suggestions:
* [spacemacs](https://github.com/syl20bnr/spacemacs) * [spacemacs](https://github.com/syl20bnr/spacemacs)
* [sublime](https://www.sublimetext.com/) * [sublime](https://www.sublimetext.com/)
Next, follow our [Git and GitHub Guide](git-guide.html) to clone and configure Next, follow our [Git and GitHub Guide](../contributing/git-guide.html) to clone and configure
your fork of zulip on your local computer. your fork of zulip on your local computer.
Once you have cloned your code locally, you can get to work. Once you have cloned your code locally, you can get to work.
@ -172,13 +172,13 @@ Next, read the following to learn more about developing for Zulip:
* [Using the Development Environment][rtd-using-dev-env] * [Using the Development Environment][rtd-using-dev-env]
* [Testing][rtd-testing] * [Testing][rtd-testing]
[install-direct]: dev-setup-non-vagrant.html#installing-directly-on-ubuntu [install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu
[install-generic]: dev-setup-non-vagrant.html#installing-manually-on-linux [install-generic]: ../development/setup-advanced.html#installing-manually-on-linux
[install-vagrant]: dev-env-first-time-contributors.html [install-vagrant]: ../development/setup-vagrant.html
[rtd-git-guide]: git-guide.html [rtd-git-guide]: ../contributing/git-guide.html
[rtd-using-dev-env]: using-dev-environment.html [rtd-using-dev-env]: using.html
[rtd-testing]: testing.html [rtd-testing]: ../testing/testing.html
[git-bash]: https://git-for-windows.github.io/ [git-bash]: https://git-for-windows.github.io/
[codeanywhere]: https://codeanywhere.com/ [codeanywhere]: https://codeanywhere.com/
[img-ca-settings]: images/codeanywhere-settings.png [img-ca-settings]: ../images/codeanywhere-settings.png
[img-ca-workspace]: images/codeanywhere-workspace.png [img-ca-workspace]: ../images/codeanywhere-workspace.png

6
docs/dev-setup-non-vagrant.md → docs/development/setup-advanced.md
View File

@ -1,4 +1,4 @@
# Zulip development environment setup without Vagrant # Advanced Setup (non-Vagrant)
Contents: Contents:
@ -28,7 +28,7 @@ development environment).
Once you've done the above setup, you can pick up the [documentation Once you've done the above setup, you can pick up the [documentation
on using the Zulip development on using the Zulip development
environment](dev-env-first-time-contributors.html#step-4-developing), environment](../development/setup-vagrant.html#step-4-developing),
ignoring the parts about `vagrant` (since you're not using it). ignoring the parts about `vagrant` (since you're not using it).
## Installing manually on Linux ## Installing manually on Linux
@ -411,7 +411,7 @@ docker run -itv $(pwd):/srv/zulip -p 9991:9991 user/zulipdev:v2 \
``` ```
You'll want to You'll want to
[read the guide for Zulip development](dev-env-first-time-contributors.html#step-4-developing) [read the guide for Zulip development](../development/setup-vagrant.html#step-4-developing)
to understand how to use the Zulip development. Note that to understand how to use the Zulip development. Note that
`start-dockers` automatically runs `tools/run-dev.py` inside the `start-dockers` automatically runs `tools/run-dev.py` inside the
container; you can then visit http://localhost:9991 to connect to your container; you can then visit http://localhost:9991 to connect to your

32
docs/dev-env-first-time-contributors.md → docs/development/setup-vagrant.md
View File

@ -24,7 +24,7 @@ environment,** check
[Troubleshooting and Common Errors](#troubleshooting-and-common-errors). If [Troubleshooting and Common Errors](#troubleshooting-and-common-errors). If
that doesn't help, please visit that doesn't help, please visit
[#provision help](https://chat.zulip.org/#narrow/stream/provision.20help) [#provision help](https://chat.zulip.org/#narrow/stream/provision.20help)
in the [Zulip development community server](chat-zulip-org.html) for in the [Zulip development community server](../contributing/chat-zulip-org.html) for
real-time help, send a note to the real-time help, send a note to the
[Zulip-devel Google group](https://groups.google.com/forum/#!forum/zulip-devel) [Zulip-devel Google group](https://groups.google.com/forum/#!forum/zulip-devel)
or [file an issue](https://github.com/zulip/zulip/issues). or [file an issue](https://github.com/zulip/zulip/issues).
@ -329,7 +329,7 @@ does the following:
downloads all required dependencies, sets up the python environment for downloads all required dependencies, sets up the python environment for
the Zulip development server, and initializes a default test the Zulip development server, and initializes a default test
database. We call this process "provisioning", and it is documented database. We call this process "provisioning", and it is documented
in some detail in our [dependencies documentation](dependencies.html). in some detail in our [dependencies documentation](../subsystems/dependencies.html).
You will need an active internet connection during the entire You will need an active internet connection during the entire
process. (See [Specifying a proxy](#specifying-a-proxy) if you need a process. (See [Specifying a proxy](#specifying-a-proxy) if you need a
@ -341,7 +341,7 @@ documented in the
[Troubleshooting and Common Errors](#troubleshooting-and-common-errors) [Troubleshooting and Common Errors](#troubleshooting-and-common-errors)
section. If that doesn't help, please visit section. If that doesn't help, please visit
[#provision help](https://chat.zulip.org/#narrow/stream/provision.20help) [#provision help](https://chat.zulip.org/#narrow/stream/provision.20help)
in the [Zulip development community server](chat-zulip-org.html) for in the [Zulip development community server](../contributing/chat-zulip-org.html) for
real-time help. real-time help.
On Windows, you will see `The system cannot find the path specified.` message On Windows, you will see `The system cannot find the path specified.` message
@ -435,7 +435,7 @@ navigating to <http://localhost:9991/> in the browser on your main machine.
You should see something like this: You should see something like this:
![Image of Zulip development environment](images/zulip-dev.png) ![Image of Zulip development environment](../images/zulip-dev.png)
The Zulip server will continue to run and send output to the terminal window. The Zulip server will continue to run and send output to the terminal window.
When you navigate to Zulip in your browser, check your terminal and you When you navigate to Zulip in your browser, check your terminal and you
@ -478,7 +478,7 @@ It's good to have the terminal running `run-dev.py` up as you work since error
messages including tracebacks along with every backend request will be printed messages including tracebacks along with every backend request will be printed
there. there.
See [Logging](logging.html) for further details on the run-dev.py console See [Logging](../subsystems/logging.html) for further details on the run-dev.py console
output. output.
#### Committing and pushing changes with git #### Committing and pushing changes with git
@ -507,7 +507,7 @@ After provisioning, you'll want to
If you run into any trouble, the If you run into any trouble, the
[#provision help](https://chat.zulip.org/#narrow/stream/provision.20help) [#provision help](https://chat.zulip.org/#narrow/stream/provision.20help)
in the [Zulip development community server](chat-zulip-org.html) for in the [Zulip development community server](../contributing/chat-zulip-org.html) for
is a great place to ask for help. is a great place to ask for help.
#### Rebuilding the development environment #### Rebuilding the development environment
@ -603,7 +603,7 @@ If these solutions aren't working for you or you encounter an issue not
documented below, there are a few ways to get further help: documented below, there are a few ways to get further help:
* Ask in [#provision help](https://chat.zulip.org/#narrow/stream/provision.20help) * Ask in [#provision help](https://chat.zulip.org/#narrow/stream/provision.20help)
in the [Zulip development community server](chat-zulip-org.html), in the [Zulip development community server](../contributing/chat-zulip-org.html),
* send a note to the [Zulip-devel Google * send a note to the [Zulip-devel Google
group](https://groups.google.com/forum/#!forum/zulip-devel), or group](https://groups.google.com/forum/#!forum/zulip-devel), or
* [File an issue](https://github.com/zulip/zulip/issues). * [File an issue](https://github.com/zulip/zulip/issues).
@ -886,7 +886,7 @@ Likely causes are:
1. Networking issues 1. Networking issues
2. Insufficient RAM. Check whether you've allotted at least two 2. Insufficient RAM. Check whether you've allotted at least two
gigabytes of RAM, which is the minimum Zulip gigabytes of RAM, which is the minimum Zulip
[requires](dev-env-first-time-contributors.html#requirements). If [requires](../development/setup-vagrant.html#requirements). If
not, go to your VM settings and increase the RAM, then restart not, go to your VM settings and increase the RAM, then restart
the VM. the VM.
@ -967,7 +967,7 @@ patching file bundler.rb
#### Permissions errors when running the test suite in LXC #### Permissions errors when running the test suite in LXC
See ["Possible testing issues"](testing.html#possible-testing-issues). See ["Possible testing issues"](../testing/testing.html#possible-testing-issues).
### Specifying a proxy ### Specifying a proxy
@ -1029,13 +1029,13 @@ for the IP address that means any IP address can connect to your development ser
[vmware-fusion-dl]: http://www.vmware.com/products/fusion.html [vmware-fusion-dl]: http://www.vmware.com/products/fusion.html
[vagrant-vmware-fusion-dl]: https://www.vagrantup.com/vmware/ [vagrant-vmware-fusion-dl]: https://www.vagrantup.com/vmware/
[avoiding-sudo]: https://github.com/fgrehm/vagrant-lxc#avoiding-sudo-passwords [avoiding-sudo]: https://github.com/fgrehm/vagrant-lxc#avoiding-sudo-passwords
[install-advanced]: dev-setup-non-vagrant.html [install-advanced]: ../development/setup-advanced.html
[lxc-sf]: https://github.com/fgrehm/vagrant-lxc/wiki/FAQ#help-my-shared-folders-have-the-wrong-owner [lxc-sf]: https://github.com/fgrehm/vagrant-lxc/wiki/FAQ#help-my-shared-folders-have-the-wrong-owner
[rtd-git-guide]: git-guide.html [rtd-git-guide]: ../contributing/git-guide.html
[rtd-testing]: testing.html [rtd-testing]: ../testing/testing.html
[rtd-using-dev-env]: using-dev-environment.html [rtd-using-dev-env]: using.html
[rtd-dev-remote]: dev-remote.html [rtd-dev-remote]: remote.html
[git-bash]: https://git-for-windows.github.io/ [git-bash]: https://git-for-windows.github.io/
[bash-admin-setup]: https://superuser.com/questions/1002262/run-applications-as-administrator-by-default-in-windows-10 [bash-admin-setup]: https://superuser.com/questions/1002262/run-applications-as-administrator-by-default-in-windows-10
[set-up-git]: git-guide.html#set-up-git [set-up-git]: ../contributing/git-guide.html#set-up-git
[travis-ci]: git-guide.html#step-3-configure-travis-ci-continuous-integration [travis-ci]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration

4
docs/using-dev-environment.md → docs/development/using.md
View File

@ -51,5 +51,5 @@ restart if it crashes, and `upgrade-zulip` will take care of running
migrations and then cleanly restaring the server for you). migrations and then cleanly restaring the server for you).
[django-runserver]: https://docs.djangoproject.com/en/1.8/ref/django-admin/#runserver-port-or-address-port [django-runserver]: https://docs.djangoproject.com/en/1.8/ref/django-admin/#runserver-port-or-address-port
[new-feature-tutorial]: new-feature-tutorial.html [new-feature-tutorial]: ../tutorials/new-feature-tutorial.html
[testing-docs]: testing.html [testing-docs]: ../testing/testing.html

129
docs/index.rst
View File

@ -31,138 +31,67 @@ is your first time here, you may want to start with
Contents: Contents:
* :ref:`overview` * :ref:`Overview <overview>`
* :ref:`zulip-in-production` * :ref:`Zulip in Production <zulip-in-production>`
* :ref:`development-environment` * :ref:`Development Environment <development-environment>`
* :ref:`developer-tutorials` * :ref:`Developer Tutorials <developer-tutorials>`
* :ref:`code-contribution-guide` * :ref:`Code Contribution Guide <code-contribution-guide>`
* :ref:`code-testing` * :ref:`Code Testing <code-testing>`
* :ref:`subsystem-documentation` * :ref:`Subsystem Documentation <subsystem-documentation>`
* :ref:`Translating <translating>`
.. _overview: .. _overview:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 3
:caption: Overview
readme-symlink overview/index
contributing
architecture-overview
directory-structure
roadmap
changelog
.. _zulip-in-production: .. _zulip-in-production:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 3
:caption: Zulip in production
Production overview <prod> production/index
prod-requirements
Installing a production server <prod-install>
prod-troubleshooting
prod-customize
prod-mobile-push-notifications
prod-maintain-secure-upgrade
security-model
prod-authentication-methods
prod-postgres
.. _development-environment: .. _development-environment:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 3
:caption: Development environment
Development environment installation <dev-overview> development/index
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>
.. _developer-tutorials: .. _developer-tutorials:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 3
:caption: Developer tutorials
integration-guide tutorials/index
integration-docs-guide
webhook-walkthrough
new-feature-tutorial
writing-views
life-of-a-request
reading-list
screenshot-and-gif-software
fixing-commits
git-cheat-sheet-detailed
git-cheat-sheet
shell-tips
working-copies
.. _code-contribution-guide: .. _code-contribution-guide:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 3
:caption: Code contribution guide
git-guide contributing/index
version-control
code-style
mypy
code-reviewing
chat-zulip-org
zulipbot-usage
accessibility
bug-reports
.. _code-testing: .. _code-testing:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 3
:caption: Code testing
testing testing/index
linters
testing-with-django
testing-with-node
testing-with-casper
travis
manual-testing
.. _subsystem-documentation: .. _subsystem-documentation:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 3
:caption: Subsystem documentation
dependencies subsystems/index
settings
events-system .. _translating:
queuing
custom-apps .. toctree::
pointer :maxdepth: 3
markdown
realms translating/index
management-commands
front-end-build-process
schema-migrations
html_css
hashchange-system
emoji
hotspots
full-text-search
oauth
email
analytics
translating
html-templates
client
logging
typing-indicators
release-checklist
api-release-checklist
swagger-api-docs
documentation
user-docs

3
docs/install-docker-dev.md
View File

@ -1,3 +0,0 @@
# Using Docker (experimental)
Moved to [Advanced setup (Docker)](dev-setup-non-vagrant.html#using-docker-experimental).

3
docs/install-generic-unix-dev.md
View File

@ -1,3 +0,0 @@
# Installing manually on UNIX
Moved to [Advanced setup (Installing manually on Linux)](dev-setup-non-vagrant.html#installing-manually-on-linux).

3
docs/install-ubuntu-without-vagrant-dev.md
View File

@ -1,3 +0,0 @@
# Installing directly on Ubuntu
Moved to [Advanced setup (Install directly on Ubuntu)](dev-setup-non-vagrant.html#installing-directly-on-ubuntu).

22
docs/architecture-overview.md → docs/overview/architecture-overview.md
View File

@ -10,7 +10,7 @@ is a web application written in Python 2.7 (soon to also support
Python 3) and using the Django framework. That codebase includes Python 3) and using the Django framework. That codebase includes
server-side code and the web client, as well as Python API bindings server-side code and the web client, as well as Python API bindings
and most of our integrations with other services and applications (see and most of our integrations with other services and applications (see
[the directory structure guide](directory-structure.html)). [the directory structure guide](../overview/directory-structure.html)).
[Zulip Mobile](https://github.com/zulip/zulip-mobile) is the official [Zulip Mobile](https://github.com/zulip/zulip-mobile) is the official
mobile Zulip client supporting both iOS and Android, written in mobile Zulip client supporting both iOS and Android, written in
@ -57,12 +57,12 @@ choose whether to allow anyone to register an account and join, or
only allow people who have been invited, or restrict registrations to only allow people who have been invited, or restrict registrations to
members of particular groups (using email domain names or corporate members of particular groups (using email domain names or corporate
single-sign-on login for verification). For more on security single-sign-on login for verification). For more on security
considerations, see [the security model section](security-model.html). considerations, see [the security model section](../production/security-model.html).
The default Zulip home screen is like a chronologically ordered inbox; The default Zulip home screen is like a chronologically ordered inbox;
it displays messages, starting at the oldest message that the user it displays messages, starting at the oldest message that the user
hasn't viewed yet (for more on that logic, see [the guide to the hasn't viewed yet (for more on that logic, see [the guide to the
pointer and unread counts](pointer.html)). The home screen displays pointer and unread counts](../subsystems/pointer.html)). The home screen displays
the most recent messages in all the streams a user has joined (except the most recent messages in all the streams a user has joined (except
for the streams they've muted), as well as private messages from other for the streams they've muted), as well as private messages from other
users, in strict chronological order. A user can *narrow* to view only users, in strict chronological order. A user can *narrow* to view only
@ -81,7 +81,7 @@ real-time notifications they find irrelevant.
Components Components
---------- ----------
![architecture-simple](images/architecture_simple.png) ![architecture-simple](../images/architecture_simple.png)
### Django and Tornado ### Django and Tornado
@ -113,7 +113,7 @@ exception to this is that Zulip uses websockets through Tornado to
minimize latency on the code path for **sending** messages. minimize latency on the code path for **sending** messages.
There is detailed documentation on the There is detailed documentation on the
[real-time push and event queue system](events-system.html); most of [real-time push and event queue system](../subsystems/events-system.html); most of
the code is in `zerver/tornado`. the code is in `zerver/tornado`.
#### HTML templates, JavaScript, etc. #### HTML templates, JavaScript, etc.
@ -126,10 +126,10 @@ live-rendering HTML from JavaScript for things like the main message
feed. feed.
For more details on the frontend, see our documentation on For more details on the frontend, see our documentation on
[translation](translating.html), [translation](../translating/translating.html),
[templates](html-templates.html), [templates](../subsystems/html-templates.html),
[directory structure](directory-structure.html), and [directory structure](../overview/directory-structure.html), and
[the static asset pipeline](front-end-build-process.html). [the static asset pipeline](../subsystems/front-end-build-process.html).
[Jinja2]: http://jinja.pocoo.org/ [Jinja2]: http://jinja.pocoo.org/
[Handlebars]: http://handlebarsjs.com/ [Handlebars]: http://handlebarsjs.com/
@ -180,7 +180,7 @@ processes that process event queues. We use event queues for the kinds
of tasks that are best run in the background because they are of tasks that are best run in the background because they are
expensive (in terms of performance) and don't have to be synchronous expensive (in terms of performance) and don't have to be synchronous
--- e.g., sending emails or updating analytics. Also see [the queuing --- e.g., sending emails or updating analytics. Also see [the queuing
guide](queuing.html). guide](../subsystems/queuing.html).
### memcached ### memcached
@ -227,7 +227,7 @@ processes started by Supervisor are queue processors that continually
pull things out of a RabbitMQ queue and handle them; they are defined pull things out of a RabbitMQ queue and handle them; they are defined
in `zerver/worker/queue_processors.py`. in `zerver/worker/queue_processors.py`.
Also see [the queuing guide](queuing.html). Also see [the queuing guide](../subsystems/queuing.html).
### PostgreSQL ### PostgreSQL

8
docs/changelog.md → docs/overview/changelog.md
View File

@ -99,9 +99,9 @@ Backend and scaling
minimizes disruption by running these first, before beginning the minimizes disruption by running these first, before beginning the
user-facing downtime. However, if you'd like to watch the downtime user-facing downtime. However, if you'd like to watch the downtime
phase of the upgrade closely, we recommend phase of the upgrade closely, we recommend
[running them first manually](expensive-migrations.html) and as well [running them first manually](../production/expensive-migrations.html) and as well
as the usual trick of as the usual trick of
[doing an apt upgrade first](prod-maintain-secure-upgrade.html#applying-ubuntu-system-updates). [doing an apt upgrade first](../production/maintain-secure-upgrade.html#applying-ubuntu-system-updates).
* We've removed support for an uncommon legacy deployment model where * We've removed support for an uncommon legacy deployment model where
a Zulip server served multiple organizations on the same domain. a Zulip server served multiple organizations on the same domain.
@ -111,7 +111,7 @@ Backend and scaling
This change should have no effect for the vast majority of Zulip This change should have no effect for the vast majority of Zulip
servers that only have one organization. If you manage a server servers that only have one organization. If you manage a server
that hosts multiple organizations, you'll want to read [our guide on that hosts multiple organizations, you'll want to read [our guide on
multiple organizations](prod-multiple-organizations.html). multiple organizations](../production/multiple-organizations.html).
* We simplified the configuration for our password strength checker to * We simplified the configuration for our password strength checker to
be much more intuitive. If you were using the be much more intuitive. If you were using the
@ -259,7 +259,7 @@ Zulip apps.
Hungarian, Polish, Dutch, Russian, Bulgarian, Portuguese, Hungarian, Polish, Dutch, Russian, Bulgarian, Portuguese,
Serbian, Malayalam, Korean, and Italian). Serbian, Malayalam, Korean, and Italian).
[mobile-push]: https://zulip.readthedocs.io/en/latest/prod-mobile-push-notifications.html [mobile-push]: ../production/mobile-push-notifications.html
[electron-app]: https://github.com/zulip/zulip-electron/releases [electron-app]: https://github.com/zulip/zulip-electron/releases
[ios-app]: https://itunes.apple.com/us/app/zulip/id1203036395 [ios-app]: https://itunes.apple.com/us/app/zulip/id1203036395

1
docs/overview/contributing.md Symbolic link
View File

@ -0,0 +1 @@
../../CONTRIBUTING.md

12
docs/directory-structure.md → docs/overview/directory-structure.md
View File

@ -4,7 +4,7 @@ This page documents the Zulip directory structure, where to find
things, and how to decide where to put a file. things, and how to decide where to put a file.
You may also find the [new application feature You may also find the [new application feature
tutorial](new-feature-tutorial.html) helpful for understanding the tutorial](../tutorials/new-feature-tutorial.html) helpful for understanding the
flow through these files. flow through these files.
### Core Python files ### Core Python files
@ -25,15 +25,15 @@ paths will be familiar to Django developers.
* `zerver/views/*.py` Most [Django views](https://docs.djangoproject.com/en/1.8/topics/http/views/). * `zerver/views/*.py` Most [Django views](https://docs.djangoproject.com/en/1.8/topics/http/views/).
* `zerver/webhooks/` Webhook views and tests for [Zulip webhook integrations](integration-guide.html). * `zerver/webhooks/` Webhook views and tests for [Zulip webhook integrations](../tutorials/integration-guide.html).
* `zerver/tornado/views.py` Tornado views. * `zerver/tornado/views.py` Tornado views.
* `zerver/worker/queue_processors.py` [Queue workers](queuing.html). * `zerver/worker/queue_processors.py` [Queue workers](../subsystems/queuing.html).
* `zerver/lib/*.py` Most library code. * `zerver/lib/*.py` Most library code.
* `zerver/lib/bugdown/` [Backend Markdown processor](markdown.html). * `zerver/lib/bugdown/` [Backend Markdown processor](../subsystems/markdown.html).
* `zproject/backends.py` [Authentication backends](https://docs.djangoproject.com/en/1.8/topics/auth/customizing/). * `zproject/backends.py` [Authentication backends](https://docs.djangoproject.com/en/1.8/topics/auth/customizing/).
@ -41,7 +41,7 @@ paths will be familiar to Django developers.
### HTML Templates ### HTML Templates
See [our docs](html-templates.html) for details on Zulip's See [our docs](../subsystems/html-templates.html) for details on Zulip's
templating systems. templating systems.
* `templates/zerver/` For [Jinja2](http://jinja.pocoo.org/) templates * `templates/zerver/` For [Jinja2](http://jinja.pocoo.org/) templates
@ -86,7 +86,7 @@ These are distinguished from scripts, below, by needing to run a
Django context (i.e. with database access). Django context (i.e. with database access).
* `zerver/management/commands/` * `zerver/management/commands/`
[Management commands](management-commands.html) one might run at a [Management commands](../subsystems/management-commands.html) one might run at a
production deployment site (e.g. scripts to change a value or production deployment site (e.g. scripts to change a value or
deactivate a user properly). deactivate a user properly).

13
docs/overview/index.rst Normal file
View File

@ -0,0 +1,13 @@
########
Overview
########
.. toctree::
:maxdepth: 3
readme-symlink
contributing
architecture-overview
directory-structure
roadmap
changelog

1
docs/overview/readme-symlink.md Symbolic link
View File

@ -0,0 +1 @@
../../README.md

0
docs/roadmap.md → docs/overview/roadmap.md
View File

2
docs/password-strength.md
View File

@ -4,7 +4,7 @@ When a user tries to set a password, we use [zxcvbn][zxcvbn] to check
that it isn't a weak one. that it isn't a weak one.
See discussion in [our main docs for server See discussion in [our main docs for server
admins](security-model.html#passwords). This doc explains in more admins](../production/security-model.html#passwords). This doc explains in more
detail how we set the default threshold (`PASSWORD_MIN_GUESSES`) we use. detail how we set the default threshold (`PASSWORD_MIN_GUESSES`) we use.
First, read the doc section there. (It's short.) First, read the doc section there. (It's short.)

0
docs/prod-authentication-methods.md → docs/production/authentication-methods.md
View File

8
docs/prod-customize.md → docs/production/customize.md
View File

@ -29,7 +29,7 @@ default the email backend is enabled.
If you want an additional or different authentication backend, you will need to If you want an additional or different authentication backend, you will need to
uncomment one or more and then do any additional configuration required for uncomment one or more and then do any additional configuration required for
that backend as documented in the `settings.py` file. See that backend as documented in the `settings.py` file. See
the [section on Authentication](prod-authentication-methods.html) for more detail on the available the [section on Authentication](../production/authentication-methods.html) for more detail on the available
authentication backends and how to configure them. authentication backends and how to configure them.
### Mobile and desktop apps ### Mobile and desktop apps
@ -45,7 +45,7 @@ their push notification protocols, the Zulip mobile apps for
[Android](https://play.google.com/store/apps/details?id=com.zulipmobile) [Android](https://play.google.com/store/apps/details?id=com.zulipmobile)
can only receive push notifications from a single Zulip server. We can only receive push notifications from a single Zulip server. We
have configured that server to be `push.zulipchat.com`, and offer a have configured that server to be `push.zulipchat.com`, and offer a
[push notification forwarding service](prod-mobile-push-notifications.html) that [push notification forwarding service](mobile-push-notifications.html) that
forwards push notifications through our servers to mobile devices. forwards push notifications through our servers to mobile devices.
Read the linked documentation for instructions on how to register for Read the linked documentation for instructions on how to register for
and configure this service. and configure this service.
@ -74,7 +74,7 @@ been added in more recent versions of Zulip.
Since Zulip's settings file is a Python script, there are a number of Since Zulip's settings file is a Python script, there are a number of
other things that one can configure that are not documented; ask on other things that one can configure that are not documented; ask on
[chat.zulip.org](https://zulip.readthedocs.io/en/latest/chat-zulip-org.html) [chat.zulip.org](../contributing/chat-zulip-org.html
if there's something you'd like to do but can't figure out how to. if there's something you'd like to do but can't figure out how to.
[settings-py-template]: https://github.com/zulip/zulip/blob/master/zproject/prod_settings_template.py [settings-py-template]: https://github.com/zulip/zulip/blob/master/zproject/prod_settings_template.py
@ -102,4 +102,4 @@ Zulip documentation cover everything anyone might want to know about
running Zulip in production. running Zulip in production.
Next: [Maintaining and upgrading Zulip in Next: [Maintaining and upgrading Zulip in
production](prod-maintain-secure-upgrade.html). production](../production/maintain-secure-upgrade.html).

0
docs/prod-email.md → docs/production/email.md
View File

0
docs/expensive-migrations.md → docs/production/expensive-migrations.md
View File

17
docs/production/index.rst Normal file
View File

@ -0,0 +1,17 @@
###################
Zulip in Production
###################
.. toctree::
:maxdepth: 3
Production overview <overview>
requirements
Installing a production server <install>
troubleshooting
customize
mobile-push-notifications
maintain-secure-upgrade
security-model
authentication-methods
postgres

2
docs/prod-install-existing-server.md → docs/production/install-existing-server.md
View File

@ -78,5 +78,5 @@ We don't provide a convenient way to uninstall a Zulip server.
Most of the limitations are things we'd accept a pull request to fix; Most of the limitations are things we'd accept a pull request to fix;
we welcome contributions to shrink this list of gotchas. Chat with us we welcome contributions to shrink this list of gotchas. Chat with us
in the [chat.zulip.org community](chat-zulip-org.html) if you're in the [chat.zulip.org community](../contributing/chat-zulip-org.html if you're
interested in helping! interested in helping!

22
docs/prod-install.md → docs/production/install.md
View File

@ -2,10 +2,10 @@
Make sure you want to install a Zulip production server. If you'd Make sure you want to install a Zulip production server. If you'd
instead like to test or develop a new feature, we recommend the instead like to test or develop a new feature, we recommend the
[Zulip server development environment](dev-overview.html#requirements) instead. [Zulip server development environment](../development/overview.html#requirements) instead.
You will need an Ubuntu system that satisfies You will need an Ubuntu system that satisfies
[the installation requirements](prod-requirements.html). In short, [the installation requirements](../production/requirements.html). In short,
you need: you need:
* Either a dedicated machine, or a fresh VM on an existing machine. * Either a dedicated machine, or a fresh VM on an existing machine.
* Ubuntu 16.04 Xenial or Ubuntu 14.04 Trusty, 64-bit. If you have a * Ubuntu 16.04 Xenial or Ubuntu 14.04 Trusty, 64-bit. If you have a
@ -87,12 +87,12 @@ heading `### MANDATORY SETTINGS`. These settings include:
- `EMAIL_HOST`, `EMAIL_HOST_USER`: credentials for an outgoing email - `EMAIL_HOST`, `EMAIL_HOST_USER`: credentials for an outgoing email
(aka "SMTP") server that Zulip can use to send emails. See (aka "SMTP") server that Zulip can use to send emails. See
[our guide for outgoing email](prod-email.html) for help configuring [our guide for outgoing email](email.html) for help configuring
this. this.
## Step 4: Test email configuration ## Step 4: Test email configuration
[Test your outgoing email configuration](prod-email.html#testing-and-troubleshooting). [Test your outgoing email configuration](email.html#testing-and-troubleshooting).
This is important to test now, because email configuration errors are This is important to test now, because email configuration errors are
common, and your outgoing email configuration needs to be working in common, and your outgoing email configuration needs to be working in
order for you to complete the installation. order for you to complete the installation.
@ -119,7 +119,7 @@ in your Zulip installation.
## Step 6: Create a Zulip organization and login ## Step 6: Create a Zulip organization and login
* Run the organization (realm) creation [management * Run the organization (realm) creation [management
command](prod-maintain-secure-upgrade.html#management-commands) : command](../production/maintain-secure-upgrade.html#management-commands) :
``` ```
su zulip # If you weren't already the zulip user su zulip # If you weren't already the zulip user
@ -130,13 +130,13 @@ command](prod-maintain-secure-upgrade.html#management-commands) :
new Zulip organization on your server. new Zulip organization on your server.
* Open the generated link with your web browser. You'll see the "Create * Open the generated link with your web browser. You'll see the "Create
organization" page ([screenshot here](_static/zulip-create-realm.png)). organization" page ([screenshot here](../_static/zulip-create-realm.png)).
Enter your email address and click *Create organization*. Enter your email address and click *Create organization*.
* Check your email to find the confirmation email and click the * Check your email to find the confirmation email and click the
link. You'll be prompted to finish setting up your organization and link. You'll be prompted to finish setting up your organization and
initial administrator user ([screenshot initial administrator user ([screenshot
here](_static/zulip-create-user-and-org.png)). Complete this form and here](../_static/zulip-create-user-and-org.png)). Complete this form and
log in! log in!
**Congratulations!** You are logged in as an organization **Congratulations!** You are logged in as an organization
@ -150,8 +150,8 @@ to get important announcements for Zulip server administrators about
new releases, security issues, etc. new releases, security issues, etc.
* [Follow Zulip on Twitter](https://twitter.com/zulip) to get Zulip news. * [Follow Zulip on Twitter](https://twitter.com/zulip) to get Zulip news.
* [Learn how to setup your new Zulip organization][realm-admin-docs]. * [Learn how to setup your new Zulip organization][realm-admin-docs].
* [Learn how further configure your Zulip server](prod-customize.html). * [Learn how further configure your Zulip server](customize.html).
* [Learn about maintaining a production Zulip server](prod-maintain-secure-upgrade.html). * [Learn about maintaining a production Zulip server](../production/maintain-secure-upgrade.html).
## Troubleshooting ## Troubleshooting
@ -165,12 +165,12 @@ and can just skip that step.
* If you get an error after `scripts/setup/install` completes, check * If you get an error after `scripts/setup/install` completes, check
the bottom of `/var/log/zulip/errors.log` for a traceback, and consult the bottom of `/var/log/zulip/errors.log` for a traceback, and consult
the [troubleshooting section](prod-troubleshooting.html) for advice on the [troubleshooting section](troubleshooting.html) for advice on
how to debug. how to debug.
* If that doesn't help, please visit * If that doesn't help, please visit
[#production help](https://chat.zulip.org/#narrow/stream/production.20help) [#production help](https://chat.zulip.org/#narrow/stream/production.20help)
in the [Zulip development community server](chat-zulip-org.html) for in the [Zulip development community server](../contributing/chat-zulip-org.html for
realtime help or email zulip-help@googlegroups.com with the full realtime help or email zulip-help@googlegroups.com with the full
traceback, and we'll try to help you out! Please provide details like traceback, and we'll try to help you out! Please provide details like
the full traceback from the bottom of `/var/log/zulip/errors.log` in the full traceback from the bottom of `/var/log/zulip/errors.log` in

14
docs/prod-maintain-secure-upgrade.md → docs/production/maintain-secure-upgrade.md
View File

@ -12,7 +12,7 @@ secure Zulip installation, including:
You may also want to read this related content: You may also want to read this related content:
- [Security Model](security-model.html) - [Security Model](../production/security-model.html)
## Upgrading ## Upgrading
@ -229,7 +229,7 @@ lower-priority.
If you are interested in backups because you are moving from one Zulip If you are interested in backups because you are moving from one Zulip
server to another server and can't transfer a full postgres dump server to another server and can't transfer a full postgres dump
(which is definitely the simplest approach), our draft (which is definitely the simplest approach), our draft
[conversion and export design document](conversion.html) may help. [conversion and export design document](../subsystems/conversion.html) may help.
The tool is well designed and was tested carefully with dozens of The tool is well designed and was tested carefully with dozens of
realms as of mid-2016 but is not integrated into Zulip's regular realms as of mid-2016 but is not integrated into Zulip's regular
testing process, and thus it is worth asking on the Zulip developers testing process, and thus it is worth asking on the Zulip developers
@ -344,16 +344,16 @@ running Zulip with larger teams (especially >1000 users).
* For an organization with 100+ users, it's important to have more * For an organization with 100+ users, it's important to have more
than 4GB of RAM on the system. Zulip will install on a system with than 4GB of RAM on the system. Zulip will install on a system with
2GB of RAM, but with less than 3.5GB of RAM, it will run its 2GB of RAM, but with less than 3.5GB of RAM, it will run its
[queue processors](queuing.html) multithreaded to conserve memory; [queue processors](../subsystems/queuing.html) multithreaded to conserve memory;
this creates a significant performance bottleneck. this creates a significant performance bottleneck.
* [chat.zulip.org](chat-zulip-org.html), with thousands of user * [chat.zulip.org](../contributing/chat-zulip-org.html, with thousands of user
accounts and thousands of messages sent every week, has 8GB of RAM, accounts and thousands of messages sent every week, has 8GB of RAM,
4 cores, and 80GB of disk. The CPUs are essentially always idle, 4 cores, and 80GB of disk. The CPUs are essentially always idle,
but the 8GB of RAM is important. but the 8GB of RAM is important.
* We recommend using a [remote postgres * We recommend using a [remote postgres
database](prod-postgres.html) for isolation, though it is database](postgres.html) for isolation, though it is
not required. In the following, we discuss a relatively simple not required. In the following, we discuss a relatively simple
configuration with two types of servers: application servers configuration with two types of servers: application servers
(running Django, Tornado, RabbitMQ, Redis, Memcached, etc.) and (running Django, Tornado, RabbitMQ, Redis, Memcached, etc.) and
@ -407,7 +407,7 @@ welcome! This is an area we are hoping to improve.
## Securing your Zulip server ## Securing your Zulip server
Zulip's security model is discussed in Zulip's security model is discussed in
[a separate document](security-model.html). [a separate document](../production/security-model.html).
## Management commands ## Management commands
@ -486,4 +486,4 @@ There are a large number of useful management commands under
## Hosting multiple Zulip organizations ## Hosting multiple Zulip organizations
This is explained in detail on [its own page](prod-multiple-organizations.html). This is explained in detail on [its own page](../production/multiple-organizations.html).

2
docs/prod-mobile-push-notifications.md → docs/production/mobile-push-notifications.md
View File

@ -28,7 +28,7 @@ follows:
3. Uncomment the `PUSH_NOTIFICATION_BOUNCER_URL = "https://push.zulipchat.com"` 3. Uncomment the `PUSH_NOTIFICATION_BOUNCER_URL = "https://push.zulipchat.com"`
line in your `/etc/zulip/settings.py` file, and line in your `/etc/zulip/settings.py` file, and
[restart your Zulip server](prod-maintain-secure-upgrade.html#updating-settings). [restart your Zulip server](../production/maintain-secure-upgrade.html#updating-settings).
Note that if you installed Zulip older than 1.6, you'll need to add Note that if you installed Zulip older than 1.6, you'll need to add
the line (it won't be there to uncomment). the line (it won't be there to uncomment).

4
docs/prod-multiple-organizations.md → docs/production/multiple-organizations.md
View File

@ -7,7 +7,7 @@ single server.
Throughout this article, we'll assume you're working on a zulip server Throughout this article, we'll assume you're working on a zulip server
with hostname `zulip.example.com`. You may also find the more with hostname `zulip.example.com`. You may also find the more
[technically focused article on realms](realms.html) to be useful [technically focused article on realms](../subsystems/realms.html) to be useful
reading. reading.
## Subdomains ## Subdomains
@ -35,7 +35,7 @@ things:
certificates. certificates.
* Use `./manage.py generate_realm_creation_link` again to create your * Use `./manage.py generate_realm_creation_link` again to create your
new organization. Review new organization. Review
[the install instructions](prod-install.html) if you need a [the install instructions](install.html) if you need a
refresher on how this works. refresher on how this works.
For servers hosting a large number of organizations, like For servers hosting a large number of organizations, like

14
docs/prod.md → docs/production/overview.md
View File

@ -1,7 +1,7 @@
# Zulip in production # Zulip in production
To play around with Zulip and see what it looks like, check out the To play around with Zulip and see what it looks like, check out the
[Zulip community server](chat-zulip-org.html) or create a test organization [Zulip community server](../contributing/chat-zulip-org.html or create a test organization
on <https://zulipchat.com>. on <https://zulipchat.com>.
If you like what you see, you can set up Zulip for your team by If you like what you see, you can set up Zulip for your team by
@ -10,21 +10,21 @@ through how.
## Requirements ## Requirements
You'll [need a few things](prod-requirements.html) to run a production You'll [need a few things](../production/requirements.html) to run a production
Zulip server. Key requirements include: Zulip server. Key requirements include:
* a dedicated server or VM, running Ubuntu, with at least 2GB of RAM * a dedicated server or VM, running Ubuntu, with at least 2GB of RAM
(or 4GB for a large site); (or 4GB for a large site);
* a valid DNS name and SSL certificates; * a valid DNS name and SSL certificates;
* a way to send outgoing email. * a way to send outgoing email.
See [the requirements page](prod-requirements.html) for more details, See [the requirements page](../production/requirements.html) for more details,
including free options [for SSL](ssl-certificates.html) and [for including free options [for SSL](ssl-certificates.html) and [for
outgoing email](prod-email.html#free-outgoing-email-services) if you don't have outgoing email](email.html#free-outgoing-email-services) if you don't have
those already. those already.
## Install ## Install
Follow [the install instructions](prod-install.html). You'll download Follow [the install instructions](../production/install.html). You'll download
the built release tarball, run the Zulip install script, and configure the built release tarball, run the Zulip install script, and configure
a handful of required settings; then create your Zulip organization a handful of required settings; then create your Zulip organization
through your new server's web interface. through your new server's web interface.
@ -36,9 +36,9 @@ You now have a running Zulip install!
* Read [our advice on helping your community][realm-admin-docs] make * Read [our advice on helping your community][realm-admin-docs] make
the most of Zulip. the most of Zulip.
* [Customize Zulip](prod-customize.html) to your needs. * [Customize Zulip](customize.html) to your needs.
* Read about Zulip's support for backups, monitoring, and * Read about Zulip's support for backups, monitoring, and
other [important production considerations](prod-maintain-secure-upgrade.html). other [important production considerations](../production/maintain-secure-upgrade.html).
[realm-admin-docs]: https://zulipchat.com/help/getting-your-organization-started-with-zulip [realm-admin-docs]: https://zulipchat.com/help/getting-your-organization-started-with-zulip

0
docs/prod-postgres.md → docs/production/postgres.md
View File

10
docs/prod-requirements.md → docs/production/requirements.md
View File

@ -2,7 +2,7 @@
Note that if you just want to play around with Zulip and see what it looks Note that if you just want to play around with Zulip and see what it looks
like, we recommend creating an account on the like, we recommend creating an account on the
[Zulip community server](chat-zulip-org.html), or creating a test [Zulip community server](../contributing/chat-zulip-org.html, or creating a test
organization on <https://zulipchat.com>. organization on <https://zulipchat.com>.
## Server ## Server
@ -16,7 +16,7 @@ strongly recommend using either a fresh machine instance in a cloud
provider, a fresh VM, or a dedicated machine. If you decide to provider, a fresh VM, or a dedicated machine. If you decide to
disregard our advice and use a server that hosts other services, we disregard our advice and use a server that hosts other services, we
can't support you, but can't support you, but
[we do have some notes on issues you'll encounter](prod-install-existing-server.html). [we do have some notes on issues you'll encounter](install-existing-server.html).
#### Operating System #### Operating System
@ -36,7 +36,7 @@ save yourself the work of upgrading in a few months.
for organizations with a hundreds of users (active or no). for organizations with a hundreds of users (active or no).
See our See our
[documentation on scalability](prod-maintain-secure-upgrade.html#scalability) [documentation on scalability](../production/maintain-secure-upgrade.html#scalability)
for advice on hardware requirements for larger organizations. for advice on hardware requirements for larger organizations.
* Disk space: You'll need at least 10GB of free disk space for a * Disk space: You'll need at least 10GB of free disk space for a
@ -86,7 +86,7 @@ need to update the domain's A record to point to your production server.
during the signup process, missed message notifications, password during the signup process, missed message notifications, password
reset, etc.). If you don't have an existing outgoing SMTP solution, reset, etc.). If you don't have an existing outgoing SMTP solution,
read about read about
[free outgoing SMTP options and options for prototyping](prod-email.html#free-outgoing-email-services). [free outgoing SMTP options and options for prototyping](email.html#free-outgoing-email-services).
Once you have met these requirements, see [full instructions for installing Once you have met these requirements, see [full instructions for installing
Zulip in production](prod-install.html). Zulip in production](../production/install.html).

2
docs/security-model.md → docs/production/security-model.md
View File

@ -37,7 +37,7 @@ announcement).
* The preferred way to login to Zulip is using an SSO solution like * The preferred way to login to Zulip is using an SSO solution like
Google Auth, LDAP, or similar, but Zulip also supports password Google Auth, LDAP, or similar, but Zulip also supports password
authentication. See authentication. See
[the authentication methods documentation](prod-authentication-methods.html) [the authentication methods documentation](../production/authentication-methods.html)
for details on Zulip's available authentication methods. for details on Zulip's available authentication methods.
### Passwords ### Passwords

0
docs/ssl-certificates.md → docs/production/ssl-certificates.md
View File

6
docs/prod-troubleshooting.md → docs/production/troubleshooting.md
View File

@ -6,8 +6,8 @@ supervisorctl](#using-supervisorctl), to learn how to use the
Supervisor client to monitor and manage services. Supervisor client to monitor and manage services.
If you haven't already, now might be a good time to read Zulip's [architectural If you haven't already, now might be a good time to read Zulip's [architectural
overview](architecture-overview.html), particularly the overview](../overview/architecture-overview.html), particularly the
[Components](architecture-overview.html#components) section. This will help you [Components](../overview/architecture-overview.html#components) section. This will help you
understand the many services Zulip uses. understand the many services Zulip uses.
If you encounter issues while running Zulip, take a look at Zulip's logs, which If you encounter issues while running Zulip, take a look at Zulip's logs, which
@ -130,4 +130,4 @@ problems and how to resolve them:
attempt. For more on this issue, see the [Django release notes on Host header attempt. For more on this issue, see the [Django release notes on Host header
poisoning](https://www.djangoproject.com/weblog/2013/feb/19/security/#s-issue-host-header-poisoning) poisoning](https://www.djangoproject.com/weblog/2013/feb/19/security/#s-issue-host-header-poisoning)
Next: [Making your Zulip instance awesome.](prod-customize.html) Next: [Making your Zulip instance awesome.](customize.html)

1
docs/readme-symlink.md
View File

@ -1 +0,0 @@
../README.md

8
docs/request-remote-dev.md
View File

@ -63,14 +63,14 @@ Once your remote dev instance is ready:
Once you've confirmed you can connect to your remote server, take a look at: Once you've confirmed you can connect to your remote server, take a look at:
* [developing remotely](dev-remote.html) for tips on using the remote dev * [developing remotely](remote.html) for tips on using the remote dev
instance, and instance, and
* our [Git & GitHub Guide](git-guide.html) to learn how to use Git with Zulip. * our [Git & GitHub Guide](../contributing/git-guide.html) to learn how to use Git with Zulip.
Next, read the following to learn more about developing for Zulip: Next, read the following to learn more about developing for Zulip:
* [Using the Development Environment](using-dev-environment.html) * [Using the Development Environment](using.html)
* [Testing](testing.html) * [Testing](../testing/testing.html)
[github-join]: https://github.com/join [github-join]: https://github.com/join
[github-help-add-ssh-key]: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/ [github-help-add-ssh-key]: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/

0
docs/analytics.md → docs/subsystems/analytics.md
View File

0
docs/api-release-checklist.md → docs/subsystems/api-release-checklist.md
View File

2
docs/client.md → docs/subsystems/client.md
View File

@ -35,4 +35,4 @@ object as `request.client`.
In most integrations, `request.client` is then passed to In most integrations, `request.client` is then passed to
`check_send_stream_message`, where it is used to keep track of which client `check_send_stream_message`, where it is used to keep track of which client
sent the message (which in turn is used by analytics). For more sent the message (which in turn is used by analytics). For more
information, see [the webhook walkthrough](webhook-walkthrough.html). information, see [the webhook walkthrough](../tutorials/webhook-walkthrough.html).

2
docs/conversion.md → docs/subsystems/conversion.md
View File

@ -33,7 +33,7 @@ document:
This document focuses almost entirely on the **export** piece. Issues This document focuses almost entirely on the **export** piece. Issues
with getting Zulip itself running are out of scope here; see [the with getting Zulip itself running are out of scope here; see [the
production installation instructions](index.html#zulip-in-production). production installation instructions](../index.html#zulip-in-production).
As for the import side of things, we only touch on it implicitly. (My As for the import side of things, we only touch on it implicitly. (My
reasoning was that we *had* to get the export piece right in a timely reasoning was that we *had* to get the export piece right in a timely
fashion, even if it meant we would have to sort out some straggling fashion, even if it meant we would have to sort out some straggling

2
docs/custom-apps.md → docs/subsystems/custom-apps.md
View File

@ -177,7 +177,7 @@ you basically have to solve these problems:
Zulip actually supports a bunch of integrations out-of-the-box that Zulip actually supports a bunch of integrations out-of-the-box that
perform as **World Readers**. perform as **World Readers**.
The [three different integration models](integration-guide.html#types-of-integrations) The [three different integration models](../tutorials/integration-guide.html#types-of-integrations)
basically differ in where they perform the main functions of a basically differ in where they perform the main functions of a
**World Reader**. **World Reader**.

14
docs/dependencies.md → docs/subsystems/dependencies.md
View File

@ -74,12 +74,12 @@ the backend, but does in JavaScript.
For the third-party services like Postgres, Redis, Nginx, and RabbitMQ For the third-party services like Postgres, Redis, Nginx, and RabbitMQ
that are documented in the that are documented in the
[architecture overview](architecture-overview.html), we rely on the [architecture overview](../overview/architecture-overview.html), we rely on the
versions of those packages provided alongside the Linux distribution versions of those packages provided alongside the Linux distribution
on which Zulip is deployed. Because Zulip on which Zulip is deployed. Because Zulip
[only supports Ubuntu in production](prod-requirements.html), this [only supports Ubuntu in production](../production/requirements.html), this
usually means `apt`, though we do support usually means `apt`, though we do support
[other platforms in development](dev-setup-non-vagrant.html). Since [other platforms in development](../development/setup-advanced.html). Since
we don't control the versions of these dependencies, we avoid relying we don't control the versions of these dependencies, we avoid relying
on specific versions of these packages wherever possible. on specific versions of these packages wherever possible.
@ -197,7 +197,7 @@ reasoning here.
dependencies in the `yarn.lock` file; `yarn upgrade` updates the dependencies in the `yarn.lock` file; `yarn upgrade` updates the
`yarn.lock` files. `yarn.lock` files.
* `tools/update-prod-static`. This process is discussed in detail in * `tools/update-prod-static`. This process is discussed in detail in
the [static asset pipeline](front-end-build-process.html) article, the [static asset pipeline](../subsystems/front-end-build-process.html) article,
but we don't use the `node_modules` directories directly in but we don't use the `node_modules` directories directly in
production. Instead, static assets are compiled using our static production. Instead, static assets are compiled using our static
asset pipeline and it is the compiled assets that are served asset pipeline and it is the compiled assets that are served
@ -241,7 +241,7 @@ Zulip uses the [iamcal emoji data package][iamcal] for its emoji data
and sprite sheets. We download this dependency using `npm`, and then and sprite sheets. We download this dependency using `npm`, and then
have a tool, `tools/setup/build_emoji`, which reformats the emoji data have a tool, `tools/setup/build_emoji`, which reformats the emoji data
into the files under `static/generated/emoji`. Those files are in into the files under `static/generated/emoji`. Those files are in
turn used by our [markdown processor](markdown.html) and turn used by our [markdown processor](../subsystems/markdown.html) and
`tools/update-prod-static` to make Zulip's emoji work in the various `tools/update-prod-static` to make Zulip's emoji work in the various
environments where they need to be displayed. environments where they need to be displayed.
@ -256,7 +256,7 @@ files and a few large ones. There is a more extended article on our
### Translations data ### Translations data
Zulip's [translations infrastructure](translating.html) generates Zulip's [translations infrastructure](../translating/translating.html) generates
several files from the source data, which we manage similar to our several files from the source data, which we manage similar to our
emoji, but without the caching (and thus without the emoji, but without the caching (and thus without the
garbage-collection). New translations data is downloaded from garbage-collection). New translations data is downloaded from
@ -288,7 +288,7 @@ usually one needs to think about making changes in 3 places:
* `tools/lib/provision.py`. This is the main provisioning script, * `tools/lib/provision.py`. This is the main provisioning script,
used by most developers to maintain their development environment. used by most developers to maintain their development environment.
* `docs/dev-setup-non-vagrant.md`. This is our "manual installation" * `docs/development/dev-setup-non-vagrant.md`. This is our "manual installation"
documentation. Strategically, we'd like to move the support for more documentation. Strategically, we'd like to move the support for more
versions of Linux from here into `tools/lib/provision.py`. versions of Linux from here into `tools/lib/provision.py`.
* Production. Our tools for compiling/generating static assets need * Production. Our tools for compiling/generating static assets need

2
docs/documentation.md → docs/subsystems/documentation.md
View File

@ -1,4 +1,4 @@
# Documentation # Documentation Overview
Zulip has three major documentation systems: Zulip has three major documentation systems:

6
docs/email.md → docs/subsystems/email.md
View File

@ -2,7 +2,7 @@
This page has developer documentation on the Zulip email system. If you're This page has developer documentation on the Zulip email system. If you're
trying to configure your server to send email, you might be looking for our trying to configure your server to send email, you might be looking for our
guide to [sending outgoing email](prod-email.html). If you're trying to guide to [sending outgoing email](../production/email.html). If you're trying to
configure an email integration to receive incoming email (e.g. so that users configure an email integration to receive incoming email (e.g. so that users
can reply to missed message emails via email), you might be interested in can reply to missed message emails via email), you might be interested in
our instructions for our instructions for
@ -40,7 +40,7 @@ Email takes about a quarter second per email to process and send. Generally
speaking, if you're sending just one email, doing it in the current process speaking, if you're sending just one email, doing it in the current process
is fine. If you're sending emails in a loop, you probably want to send it is fine. If you're sending emails in a loop, you probably want to send it
from a queue. Documentation on our queueing system is available from a queue. Documentation on our queueing system is available
[here](queuing.html). [here](../subsystems/queuing.html).
## Development and testing ## Development and testing
@ -66,7 +66,7 @@ you have to first configure the following SMTP settings.
* The username `EMAIL_HOST_USER` in `zproject/dev_settings.py`. * The username `EMAIL_HOST_USER` in `zproject/dev_settings.py`.
* The password `email_password` in `zproject/dev-secrets.conf`. * The password `email_password` in `zproject/dev-secrets.conf`.
See [this](prod-email.html#free-outgoing-email-services) See [this](../production/email.html#free-outgoing-email-services)
section for instructions on obtaining SMTP details. section for instructions on obtaining SMTP details.
**Note: The base_image_uri of the images in forwarded emails would be replaced **Note: The base_image_uri of the images in forwarded emails would be replaced

4
docs/emoji.md → docs/subsystems/emoji.md
View File

@ -63,7 +63,7 @@ The `build_emoji` tool generates the set of files under
`static/generated/emoji` is a symlink to that tree; we do this in `static/generated/emoji` is a symlink to that tree; we do this in
order to cache old versions to make provisioning and production order to cache old versions to make provisioning and production
deployments super fast in the common case that we haven't changed the deployments super fast in the common case that we haven't changed the
emoji tooling). See [our dependencies document](dependencies.html) emoji tooling). See [our dependencies document](../subsystems/dependencies.html)
for more details on this strategy. for more details on this strategy.
The emoji tree generated by this process contains several import elements: The emoji tree generated by this process contains several import elements:
@ -78,7 +78,7 @@ The emoji tree generated by this process contains several import elements:
* `images/emoji/*.png`: A farm of symlinks from emoji names to the * `images/emoji/*.png`: A farm of symlinks from emoji names to the
`images/emoji/unicode/` tree. This is used to serve individual emoji `images/emoji/unicode/` tree. This is used to serve individual emoji
images, as well as for the images, as well as for the
[backend markdown processor](markdown.html) to know which emoji [backend markdown processor](../subsystems/markdown.html) to know which emoji
names exist and what unicode emoji / images they map to. In this names exist and what unicode emoji / images they map to. In this
tree, we currently include all of the emoji in `emoji-map.json`; tree, we currently include all of the emoji in `emoji-map.json`;
this means that if you send `:angry_face:`, it won't autocomplete, this means that if you send `:angry_face:`, it won't autocomplete,

4
docs/events-system.md → docs/subsystems/events-system.md
View File

@ -4,7 +4,7 @@ Zulip's "events system" is the server-to-client push system that
powers our real-time sync. This document explains how it works; to powers our real-time sync. This document explains how it works; to
read an example of how a complete feature using this system works, read an example of how a complete feature using this system works,
check out the check out the
[new application feature tutorial](new-feature-tutorial.html). [new application feature tutorial](../tutorials/new-feature-tutorial.html).
Any single-page web application like Zulip needs a story for how Any single-page web application like Zulip needs a story for how
changes made by one client are synced to other clients, though having changes made by one client are synced to other clients, though having
@ -85,7 +85,7 @@ wide range of possible clients, and make it easy for developers.
Zulip's event delivery (real-time push) system is based on Tornado, Zulip's event delivery (real-time push) system is based on Tornado,
which is ideal for handling a large number of open requests. Details which is ideal for handling a large number of open requests. Details
on Tornado are available in the on Tornado are available in the
[architecture overview](architecture-overview.html), but in short it [architecture overview](../overview/architecture-overview.html), but in short it
is good at holding open a large number of connections for a long time. is good at holding open a large number of connections for a long time.
The complete system is about 1500 lines of code in `zerver/tornado/`, The complete system is about 1500 lines of code in `zerver/tornado/`,
primarily `zerver/tornado/event_queue.py`. primarily `zerver/tornado/event_queue.py`.

4
docs/front-end-build-process.md → docs/subsystems/front-end-build-process.md
View File

@ -3,9 +3,9 @@
This page documents additional information that may be useful when This page documents additional information that may be useful when
developing new features for Zulip that require front-end changes, developing new features for Zulip that require front-end changes,
especially those that involve adding new files. For a more general especially those that involve adding new files. For a more general
overview, see the [new feature tutorial](new-feature-tutorial.html). overview, see the [new feature tutorial](../tutorials/new-feature-tutorial.html).
Our [dependencies documentation](dependencies.html) has useful Our [dependencies documentation](../subsystems/dependencies.html) has useful
relevant background as well. relevant background as well.
## Primary build process ## Primary build process

0
docs/full-text-search.md → docs/subsystems/full-text-search.md
View File

4
docs/hashchange-system.md → docs/subsystems/hashchange-system.md
View File

@ -110,6 +110,6 @@ browser, Zulip also does a few bookkeeping things on page reload (like
cleaning up its event queue, and saving any text in an open compose cleaning up its event queue, and saving any text in an open compose
box as a draft). box as a draft).
[testing-with-casper]: testing-with-casper.html [testing-with-casper]: ../testing/testing-with-casper.html
[self-server-reloads]: #server-initiated-reloads [self-server-reloads]: #server-initiated-reloads
[events-system]: events-system.html [events-system]: ../subsystems/events-system.html

0
docs/hotspots.md → docs/subsystems/hotspots.md
View File

6
docs/html-templates.md → docs/subsystems/html-templates.md
View File

@ -83,9 +83,9 @@ developers) should be tagged for [translation][].
[Jinja2]: http://jinja.pocoo.org/ [Jinja2]: http://jinja.pocoo.org/
[Handlebars]: http://handlebarsjs.com/ [Handlebars]: http://handlebarsjs.com/
[trans]: http://jinja.pocoo.org/docs/dev/templates/#i18n [trans]: http://jinja.pocoo.org/docs/dev/templates/#i18n
[i18next]: http://i18next.com [i18next]: https://www.i18next.com
[official]: http://i18next.com/translate/pluralSimple/ [official]: https://www.i18next.com/plurals.html
[helpers]: http://handlebarsjs.com/block_helpers.html [helpers]: http://handlebarsjs.com/block_helpers.html
[jconditionals]: http://jinja.pocoo.org/docs/2.9/templates/#list-of-control-structures [jconditionals]: http://jinja.pocoo.org/docs/2.9/templates/#list-of-control-structures
[hconditionals]: http://handlebarsjs.com/block_helpers.html [hconditionals]: http://handlebarsjs.com/block_helpers.html
[translation]: translating.html [translation]: ../translating/translating.html

2
docs/html_css.md → docs/subsystems/html_css.md
View File

@ -8,7 +8,7 @@ main third-party CSS library.
Zulip currently does not use any CSS preprocessors, and is organized Zulip currently does not use any CSS preprocessors, and is organized
into several files. For most pages, the CSS is combined into a single into several files. For most pages, the CSS is combined into a single
CSS file by the [static asset pipeline](front-end-build-process.html), CSS file by the [static asset pipeline](../subsystems/front-end-build-process.html),
controlled by the `PIPELINE_CSS` code in `zproject/settings.py`. controlled by the `PIPELINE_CSS` code in `zproject/settings.py`.
The CSS files are: The CSS files are:

35
docs/subsystems/index.rst Normal file
View File

@ -0,0 +1,35 @@
########################
Subsystems Documentation
########################
.. toctree::
:maxdepth: 3
dependencies
settings
events-system
queuing
custom-apps
pointer
markdown
realms
management-commands
front-end-build-process
schema-migrations
html_css
hashchange-system
emoji
hotspots
full-text-search
oauth
email
analytics
html-templates
client
logging
typing-indicators
release-checklist
api-release-checklist
swagger-api-docs
documentation
user-docs

0
docs/input-pills.md → docs/subsystems/input-pills.md
View File

2
docs/logging.md → docs/subsystems/logging.md
View File

@ -167,7 +167,7 @@ and report to the server the following whenever a message is sent:
* Whether the message was locally echoed. * Whether the message was locally echoed.
* If so, whether there was a disparity between the echoed content and * If so, whether there was a disparity between the echoed content and
the server-rendered content, which can be used for statistics on how the server-rendered content, which can be used for statistics on how
effective our [local echo system](markdown.html) is. effective our [local echo system](../subsystems/markdown.html) is.
The code is all in `zerver/lib/report.py` and `static/js/sent_messages.js`. The code is all in `zerver/lib/report.py` and `static/js/sent_messages.js`.

0
docs/management-commands.md → docs/subsystems/management-commands.md
View File

0
docs/markdown.md → docs/subsystems/markdown.md
View File

2
docs/oauth.md → docs/subsystems/oauth.md
View File

@ -1,6 +1,6 @@
# Google & GitHub authentication with OAuth 2 # Google & GitHub authentication with OAuth 2
Among the many [authentication methods](prod-authentication-methods.html) Among the many [authentication methods](../production/authentication-methods.html)
we support, a server can be configured to allow users to sign in with we support, a server can be configured to allow users to sign in with
their Google accounts or GitHub accounts, using the OAuth protocol. their Google accounts or GitHub accounts, using the OAuth protocol.

2
docs/pointer.md → docs/subsystems/pointer.md
View File

@ -90,7 +90,7 @@ browser), Zulip will preserve the state -- what (if any) narrow the
user was in, the selected message, and even exact scroll position! user was in, the selected message, and even exact scroll position!
For more on the user experience philosophy guiding these decisions, For more on the user experience philosophy guiding these decisions,
see [the architectural overview](architecture-overview.html). see [the architectural overview](../overview/architecture-overview.html).
## Unread count logic ## Unread count logic

0
docs/queuing.md → docs/subsystems/queuing.md
View File

4
docs/realms.md → docs/subsystems/realms.md
View File

@ -6,7 +6,7 @@ user documentation as an organization (the name "realm" comes from
[Kerberos](https://web.mit.edu/kerberos/)). [Kerberos](https://web.mit.edu/kerberos/)).
The The
[production docs on multiple realms](prod-multiple-organizations.html) [production docs on multiple realms](../production/multiple-organizations.html)
are likely also relevant reading. are likely also relevant reading.
## Creating Realms ## Creating Realms
@ -52,7 +52,7 @@ job.
We also recommend upgrading to at least Zulip 1.7, since older Zulip We also recommend upgrading to at least Zulip 1.7, since older Zulip
releases had much less nice handling for subdomains. See our releases had much less nice handling for subdomains. See our
[docs on using subdomains](prod-multiple-organizations.html) for [docs on using subdomains](../production/multiple-organizations.html) for
user-facing documentation on this. user-facing documentation on this.
### Working With Subdomains In Development Environment ### Working With Subdomains In Development Environment

0
docs/release-checklist.md → docs/subsystems/release-checklist.md
View File

4
docs/schema-migrations.md → docs/subsystems/schema-migrations.md
View File

@ -3,7 +3,7 @@
Zulip uses the [standard Django system for doing schema Zulip uses the [standard Django system for doing schema
migrations](https://docs.djangoproject.com/en/1.10/topics/migrations/). migrations](https://docs.djangoproject.com/en/1.10/topics/migrations/).
There is some example usage in the [new feature There is some example usage in the [new feature
tutorial](new-feature-tutorial.html). tutorial](../tutorials/new-feature-tutorial.html).
This page documents some important issues related to writing schema This page documents some important issues related to writing schema
migrations. migrations.
@ -30,7 +30,7 @@ migrations.
fix this, you can either run `./tools/renumber-migrations` which fix this, you can either run `./tools/renumber-migrations` which
renumbers your migration(s) and fixes up the "dependencies" entries in your renumbers your migration(s) and fixes up the "dependencies" entries in your
migration(s), and then rewrite your git history as needed, or you can do it migration(s), and then rewrite your git history as needed, or you can do it
manually. There is a tutorial [here](migration-renumbering.html) that manually. There is a tutorial [here](../migration-renumbering.html) that
walks you though that process. walks you though that process.
* **Atomicity**. By default, each Django migration is run atomically * **Atomicity**. By default, each Django migration is run atomically

2
docs/settings.md → docs/subsystems/settings.md
View File

@ -143,4 +143,4 @@ replaced with realm settings:
server, and in the realm settings indicating which methods the realm server, and in the realm settings indicating which methods the realm
administrator wants to allow users to login with. administrator wants to allow users to login with.
[doc-newfeat]: new-feature-tutorial.html [doc-newfeat]: ../tutorials/new-feature-tutorial.html

0
docs/swagger-api-docs.md → docs/subsystems/swagger-api-docs.md
View File

2
docs/typing-indicators.md → docs/subsystems/typing-indicators.md
View File

@ -69,7 +69,7 @@ how long they pause to think, and how frequently they get interrupted.
The server piece of typing notificiations is currently pretty The server piece of typing notificiations is currently pretty
straightforward, since we take advantage of Zulip's straightforward, since we take advantage of Zulip's
[events system](events-system.html). [events system](../subsystems/events-system.html).
We deliberately designed the server piece to be stateless, We deliberately designed the server piece to be stateless,
which minimizes the possibility of backend bugs and gives clients which minimizes the possibility of backend bugs and gives clients

0
docs/unread_messages.md → docs/subsystems/unread_messages.md
View File

4
docs/user-docs.md → docs/subsystems/user-docs.md
View File

@ -1,4 +1,4 @@
# General user guide documentation # General User Guide Documentation
Our goal is for Zulip to have complete, high-quality user-appealing Our goal is for Zulip to have complete, high-quality user-appealing
documentation about Zulip's features and how to perform certain tasks, such documentation about Zulip's features and how to perform certain tasks, such
@ -637,7 +637,7 @@ If necessary, you can add another section to your documentation. Sections
can be used to differentiate different methods of performing a task or can be used to differentiate different methods of performing a task or
describing a related task. describing a related task.
![Feature](/static/images/help/feature.png) ![Feature](../static/images/help/feature.png)
You can also conclude your documentation with some final notes. You can also conclude your documentation with some final notes.

14
docs/testing/index.rst Normal file
View File

@ -0,0 +1,14 @@
############
Code Testing
############
.. toctree::
:maxdepth: 3
testing
linters
testing-with-django
testing-with-node
testing-with-casper
travis
manual-testing

10
docs/linters.md → docs/testing/linters.md
View File

@ -11,7 +11,7 @@ but for other files, we are quite thorough about checking semantic
correctness. correctness.
Obviously, a large reason for linting code is to enforce the [Zulip Obviously, a large reason for linting code is to enforce the [Zulip
coding standards](code-style.html). But we also use the linters to coding standards](../contributing/code-style.html). But we also use the linters to
prevent common coding errors. prevent common coding errors.
We borrow some open source tools for much of our linting, and the links We borrow some open source tools for much of our linting, and the links
@ -56,7 +56,7 @@ the other lint checks.
## General considerations ## General considerations
Once you have read the [Zulip coding guidelines](code-style.html), you can Once you have read the [Zulip coding guidelines](../contributing/code-style.html), you can
be pretty confident that 99% of the code that you write will pass through be pretty confident that 99% of the code that you write will pass through
the linters fine, as long as you are thorough about keeping your code clean. the linters fine, as long as you are thorough about keeping your code clean.
And, of course, for minor oversights, `lint` is your friend, not your foe. And, of course, for minor oversights, `lint` is your friend, not your foe.
@ -68,7 +68,7 @@ extreme cases, but often it can be a simple matter of writing your code
in a slightly different style to appease the linter. If you have in a slightly different style to appease the linter. If you have
problems getting something to lint, you can submit an unfinished PR problems getting something to lint, you can submit an unfinished PR
and ask the reviewer to help you work through the lint problem, or you and ask the reviewer to help you work through the lint problem, or you
can find other people in the [Zulip Community](chat-zulip-org.html) can find other people in the [Zulip Community](../contributing/chat-zulip-org.html)
to help you. to help you.
Also, bear in mind that 100% of the lint code is open source, so if you Also, bear in mind that 100% of the lint code is open source, so if you
@ -76,7 +76,7 @@ find limitations in either the Zulip home-grown stuff or our third party
tools, feedback will be highly appreciated. tools, feedback will be highly appreciated.
Finally, one way to clean up your code is to thoroughly exercise it Finally, one way to clean up your code is to thoroughly exercise it
with tests. The [Zulip test documentation](testing.html) with tests. The [Zulip test documentation](../testing/testing.html)
describes our test system in detail. describes our test system in detail.
## Lint checks ## Lint checks
@ -97,7 +97,7 @@ The remaining lint checks occur in `./tools/run-mypy`. It is probably somewhat
of an understatement to call "mypy" a "linter," as it performs static of an understatement to call "mypy" a "linter," as it performs static
code analysis of Python type annotations throughout our Python codebase. code analysis of Python type annotations throughout our Python codebase.
Our [documentation on using mypy](mypy.html) covers mypy in more detail. Our [documentation on using mypy](../contributing/mypy.html) covers mypy in more detail.
The rest of this document pertains to the checks that occur in `./tools/lint`. The rest of this document pertains to the checks that occur in `./tools/lint`.

0
docs/manual-testing.md → docs/testing/manual-testing.md
View File

0
docs/testing-with-casper.md → docs/testing/testing-with-casper.md
View File

4
docs/testing-with-django.md → docs/testing/testing-with-django.md
View File

@ -254,7 +254,7 @@ from Django as well as our own custom helpers. Here is an example:
self.assertTrue(rate_limit_mock.called) self.assertTrue(rate_limit_mock.called)
Follow [this link](settings.html#testing-non-default-settings) for more Follow [this link](../subsystems/settings.html#testing-non-default-settings) for more
information on the "settings" context manager. information on the "settings" context manager.
A common use is to prevent a call to a third-party service from using A common use is to prevent a call to a third-party service from using
@ -367,7 +367,7 @@ the same data structure as performing an action that generates said event.
This is a bit esoteric, but if you read the tests, you will see some of This is a bit esoteric, but if you read the tests, you will see some of
the patterns. You can also learn more about our event system in the the patterns. You can also learn more about our event system in the
[new feature tutorial](new-feature-tutorial.html#handle-database-interactions). [new feature tutorial](../tutorials/new-feature-tutorial.html#handle-database-interactions).
### Negative tests ### Negative tests

0
docs/testing-with-node.md → docs/testing/testing-with-node.md
View File

10
docs/testing.md → docs/testing/testing.md
View File

@ -5,10 +5,10 @@
Zulip has a full test suite that includes many components. The most Zulip has a full test suite that includes many components. The most
important components are documented in depth in their own sections: important components are documented in depth in their own sections:
- [Django](testing-with-django.html): backend Python tests - [Django](../testing/testing-with-django.html): backend Python tests
- [Casper](testing-with-casper.html): end-to-end UI tests - [Casper](../testing/testing-with-casper.html): end-to-end UI tests
- [Node](testing-with-node.html): unit tests for JS front end code - [Node](../testing/testing-with-node.html): unit tests for JS front end code
- [Linters](linters.html): Our parallel linter suite - [Linters](../testing/linters.html): Our parallel linter suite
- [Travis CI details](travis.html): How all of these run in Travis CI - [Travis CI details](travis.html): How all of these run in Travis CI
This document covers more general testing issues, such as how to run the This document covers more general testing issues, such as how to run the
@ -104,7 +104,7 @@ This is easy to do using test fixtures (a fancy word for fixed data
used in tests) and the `mock.patch` function to specify what HTTP used in tests) and the `mock.patch` function to specify what HTTP
response should be used by the tests for every outgoing HTTP (or other response should be used by the tests for every outgoing HTTP (or other
network) request. Consult network) request. Consult
[our guide on mocking](testing-with-django.html#zulip-mocking-practices) to [our guide on mocking](../testing/testing-with-django.html#zulip-mocking-practices) to
learn how to mock network requests easily; there are also a number of learn how to mock network requests easily; there are also a number of
examples throughout the codebase. examples throughout the codebase.

2
docs/travis.md → docs/testing/travis.md
View File

@ -70,7 +70,7 @@ our configuration, you'll want to look at these closely.
that every remote branch you push will be tested, which can be that every remote branch you push will be tested, which can be
helpful when debugging something complicated. helpful when debugging something complicated.
[travis-fork]: git-guide.html#step-3-configure-travis-ci-continuous-integration [travis-fork]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration
## Performance optimizations ## Performance optimizations

0
docs/chinese.md → docs/translating/chinese.md
View File

0
docs/french.md → docs/translating/french.md
View File

0
docs/german.md → docs/translating/german.md
View File

14
docs/translating/index.rst Normal file
View File

@ -0,0 +1,14 @@
#################
Translating Zulip
#################
.. toctree::
:maxdepth: 3
translating
chinese
french
german
polish
russian
spanish

2
docs/polish.md → docs/translating/polish.md
View File

@ -34,8 +34,6 @@ Some terms are very tricky to translate, so be sure to communicate
with other Polish speakers in the community. It's all about making with other Polish speakers in the community. It's all about making
Zulip friendly and usable. Zulip friendly and usable.
# Common translations
## Special terms used in Zulip ## Special terms used in Zulip
**customization**: personalizacja, *kastomizacja* could be too awkward **customization**: personalizacja, *kastomizacja* could be too awkward

0
docs/russian.md → docs/translating/russian.md
View File

0
docs/spanish.md → docs/translating/spanish.md
View File

20
docs/translating.md → docs/translating/translating.md
View File

@ -1,4 +1,4 @@
# Translating Zulip # Translation Guidelines
To make Zulip even better for users around the world, the Zulip UI is To make Zulip even better for users around the world, the Zulip UI is
being translated into a number of major languages, including Spanish, being translated into a number of major languages, including Spanish,
@ -8,7 +8,7 @@ translating Zulip would be greatly appreciated!
If you're interested in contributing translations to Zulip, please If you're interested in contributing translations to Zulip, please
join [#translation](https://chat.zulip.org/#narrow/stream/translation) join [#translation](https://chat.zulip.org/#narrow/stream/translation)
in the [Zulip development community server](chat-zulip-org.html), and in the [Zulip development community server](../contributing/chat-zulip-org.html), and
say hello. And please join the say hello. And please join the
[Zulip project on Transifex](https://www.transifex.com/zulip/zulip/) [Zulip project on Transifex](https://www.transifex.com/zulip/zulip/)
and ask to join any languages you'd like to contribute to (or add new and ask to join any languages you'd like to contribute to (or add new
@ -39,7 +39,7 @@ language is to write a style guide, since it greatly increases the
ability of future translators to translate in a way that's consistent ability of future translators to translate in a way that's consistent
with what your work. with what your work.
### Capitalization ## Capitalization
We expect that all the English translatable strings in Zulip are We expect that all the English translatable strings in Zulip are
properly capitalized in a way consistent with how Zulip does properly capitalized in a way consistent with how Zulip does
@ -112,7 +112,7 @@ These are the steps you should follow if you want to help to translate
Zulip: Zulip:
1. Join us on Zulip and ask for access to the organization, as 1. Join us on Zulip and ask for access to the organization, as
[described](#translating-zulip) at the beginning. [described](#translation-guidelines) at the beginning.
2. Make sure you have access to Zulip's dashboard in Transifex. 2. Make sure you have access to Zulip's dashboard in Transifex.
@ -132,7 +132,7 @@ Some useful tips for your translating journey:
- When in doubt, ask for context in - When in doubt, ask for context in
[#translation](https://chat.zulip.org/#narrow/stream/translation) in [#translation](https://chat.zulip.org/#narrow/stream/translation) in
the [Zulip development community server](chat-zulip-org.html). the [Zulip development community server](../contributing/chat-zulip-org.html).
- If there are multiple possible translations for a term, search for it in - If there are multiple possible translations for a term, search for it in
the *Concordance* tool (the button with a magnet in the top right corner). the *Concordance* tool (the button with a magnet in the top right corner).
@ -149,7 +149,7 @@ Some useful tips for your translating journey:
## Testing translations ## Testing translations
This section assumes you have a This section assumes you have a
[Zulip development environment](dev-overview.html) set up. [Zulip development environment](../development/overview.html) set up.
First of all, download the updated resource files from Transifex using the First of all, download the updated resource files from Transifex using the
`tx pull -a --mode=developer` command (it will require some `tx pull -a --mode=developer` command (it will require some
@ -386,11 +386,11 @@ organizations from the command line.
[Jinja2]: http://jinja.pocoo.org/ [Jinja2]: http://jinja.pocoo.org/
[Handlebars]: http://handlebarsjs.com/ [Handlebars]: http://handlebarsjs.com/
[trans]: http://jinja.pocoo.org/docs/dev/templates/#i18n [trans]: http://jinja.pocoo.org/docs/dev/templates/#i18n
[i18next]: http://i18next.com [i18next]: https://www.i18next.com
[official]: http://i18next.com/translate/pluralSimple/ [official]: https://www.i18next.com/plurals.html
[unescape]: https://www.i18next.com/interpolation.html#unescape [unescape]: https://www.i18next.com/interpolation.html#unescape
[helpers]: http://handlebarsjs.com/block_helpers.html [helpers]: http://handlebarsjs.com/block_helpers.html
[resource]: http://i18next.com/translate/ [resource]: https://www.i18next.com/add-or-load-translations.html
[Transifex]: https://transifex.com [Transifex]: https://transifex.com
[transifexrc]: https://docs.transifex.com/client/client-configuration#transifexrc [transifexrc]: https://docs.transifex.com/client/client-configuration#transifexrc
[html-templates]: html-templates.html [html-templates]: ../subsystems/html-templates.html

0
docs/fixing-commits.md → docs/tutorials/fixing-commits.md
View File

0
docs/git-cheat-sheet-detailed.md → docs/tutorials/git-cheat-sheet-detailed.md
View File

0
docs/git-cheat-sheet.md → docs/tutorials/git-cheat-sheet.md
View File

Some files were not shown because too many files have changed in this diff Show More