mirror of https://github.com/zulip/zulip.git
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
Tim Abbott
parent
3b95a6d2d9
commit
7072fa5b37
|
|
@ -71,7 +71,7 @@ lint, management commands, etc., use `vagrant ssh`.
|
|||
At this point you should [read about using the development
|
||||
environment][using-dev].
|
||||
|
||||
[using-dev]: using-dev-environment.html
|
||||
[using-dev]: using.html
|
||||
|
||||
### Specifying a proxy
|
||||
|
||||
|
|
|
|||
|
|
@ -118,7 +118,7 @@ if not on_rtd:
|
|||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
html_theme_options = {
|
||||
'sticky_navigation': False,
|
||||
'collapse_navigation': False,
|
||||
}
|
||||
|
||||
# Add any paths that contain custom themes here, relative to this directory.
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
../CONTRIBUTING.md
|
||||
|
|
@ -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).
|
||||
For example, avoid using a pronoun like her or his in sentences like
|
||||
"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
|
||||
love meeting new people, hearing about what brought them to Zulip,
|
||||
and getting their feedback. If you're not sure where to start,
|
||||
|
|
@ -103,7 +103,7 @@ this?". Good choices include
|
|||
change being made. Tests that exclude whole classes of potential
|
||||
bugs are preferred when possible (e.g., the common test suite
|
||||
`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).
|
||||
|
||||
* *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
|
||||
sinternet](https://gist.github.com/porterjamesj/002fb27dd70df003646df46f15e898de)
|
||||
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
|
||||
[commit-messages]: version-control.html#commit-messages
|
||||
[test-writing]: testing.html
|
||||
[mypy]: mypy.html
|
||||
[git tool]: git-guide.html#fetch-a-pull-request-and-rebase
|
||||
[translation]: translating.html
|
||||
[code-style]: ../contributing/code-style.html
|
||||
[commit-messages]: ../contributing/version-control.html#commit-messages
|
||||
[test-writing]: ../testing/testing.html
|
||||
[mypy]: ../contributing/mypy.html
|
||||
[git tool]: ../contributing/git-guide.html#fetch-a-pull-request-and-rebase
|
||||
[translation]: ../translating/translating.html
|
||||
|
|
@ -163,7 +163,7 @@ Don't use it:
|
|||
### Translation tags
|
||||
|
||||
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
|
||||
messages).
|
||||
|
||||
|
|
@ -292,5 +292,5 @@ All significant new features should come with tests. See testing.
|
|||
|
||||
### 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.
|
||||
|
|
@ -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
|
||||
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
|
||||
Zulip. ([See screen cast](_static/zulip-travisci.gif).)
|
||||
Zulip. ([See screen cast](../_static/zulip-travisci.gif).)
|
||||
|
||||
## 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
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -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-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/
|
||||
[zulip-rtd-version-control]: version-control.html
|
||||
[zulip-rtd-commit-messages]: version-control.html#commit-messages
|
||||
[zulip-rtd-commit-discipline]: version-control.html#commit-discipline
|
||||
[zulip-rtd-lint-tools]: code-style.html#lint-tools
|
||||
[zulip-rtd-testing]: testing.html
|
||||
[zulip-rtd-mypy]: mypy.html
|
||||
[zulip-rtd-code-style]: code-style.html
|
||||
[zulip-rtd-version-control]: ../contributing/version-control.html
|
||||
[zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages
|
||||
[zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline
|
||||
[zulip-rtd-lint-tools]: ../contributing/code-style.html#lint-tools
|
||||
[zulip-rtd-testing]: ../testing/testing.html
|
||||
[zulip-rtd-mypy]: ../contributing/mypy.html
|
||||
[zulip-rtd-code-style]: ../contributing/code-style.html
|
||||
[zulip-rtd-travis-ci]: travis-ci.html
|
||||
[zulip-rtd-dev-overview]: dev-overview.html
|
||||
[zulip-rtd-dev-first-time]: dev-env-first-time-contributors.html
|
||||
[zulip-rtd-dev-overview]: ../development/overview.html
|
||||
[zulip-rtd-dev-first-time]: ../development/setup-vagrant.html
|
||||
[zulip-rtd-zulipbot-usage]: zulipbot-usage.html
|
||||
[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-gitxdev]: https://rowanj.github.io/gitx/
|
||||
[gitgui-ghdesktop]: https://desktop.github.com/
|
||||
|
|
@ -1538,31 +1538,31 @@ git rebase --continue
|
|||
[gitgui-gitk]: https://git-scm.com/docs/gitk
|
||||
[travis-ci]: https://travis-ci.org/
|
||||
[travis-ci-profile]: https://travis-ci.org/profile
|
||||
[screenshots-gifs]: screenshot-and-gif-software.html
|
||||
[self-setup]: git-guide.html#setup-git
|
||||
[self-how-git-is-different]: git-guide.html#how-git-is-different
|
||||
[self-git-terms]: git-guide.html#important-git-terms
|
||||
[self-get-zulip-code]: git-guide.html#get-zulip-code
|
||||
[self-use-git]: git-guide.html#using-git-as-you-work
|
||||
[self-create-pr]: git-guide.html#create-a-pull-request
|
||||
[self-update-pr]: git-guide.html#update-a-pull-request
|
||||
[self-collaborate]: git-guide.html#collaborate
|
||||
[self-review-changes]: git-guide.html#review-changes
|
||||
[self-trouble]: git-guide.html#get-and-stay-out-of-trouble
|
||||
[self-zulip-tools]: git-guide.html#zulip-specific-tools
|
||||
[self-clone-to-your-machine]: git-guide.html#step-1b-clone-to-your-machine
|
||||
[self-connect-upstream]: 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-fetch-another-branch]: git-guide.html#fetch-another-contributor-s-branch
|
||||
[self-fetch-pr]: git-guide.html#checkout-a-pull-request-locally
|
||||
[self-push-commits]: git-guide.html#push-your-commits-to-github
|
||||
[self-travisci]: git-guide.html#step-3-configure-travis-ci-continuous-integration
|
||||
[self-multiple-computers]: git-guide.html#working-from-multiple-computers
|
||||
[self-git-terms]: git-guide.html#important-git-terms
|
||||
[screenshots-gifs]: ../tutorials/screenshot-and-gif-software.html
|
||||
[self-setup]: ../contributing/git-guide.html#setup-git
|
||||
[self-how-git-is-different]: ../contributing/git-guide.html#how-git-is-different
|
||||
[self-git-terms]: ../contributing/git-guide.html#important-git-terms
|
||||
[self-get-zulip-code]: ../contributing/git-guide.html#get-zulip-code
|
||||
[self-use-git]: ../contributing/git-guide.html#using-git-as-you-work
|
||||
[self-create-pr]: ../contributing/git-guide.html#create-a-pull-request
|
||||
[self-update-pr]: ../contributing/git-guide.html#update-a-pull-request
|
||||
[self-collaborate]: ../contributing/git-guide.html#collaborate
|
||||
[self-review-changes]: ../contributing/git-guide.html#review-changes
|
||||
[self-trouble]: ../contributing/git-guide.html#get-and-stay-out-of-trouble
|
||||
[self-zulip-tools]: ../contributing/git-guide.html#zulip-specific-tools
|
||||
[self-clone-to-your-machine]: ../contributing/git-guide.html#step-1b-clone-to-your-machine
|
||||
[self-connect-upstream]: ../contributing/git-guide.html#step-1c-connect-your-fork-to-zulip-upstream
|
||||
[self-keep-up-to-date]: ../contributing/git-guide.html#keep-your-fork-up-to-date
|
||||
[self-fetch-another-branch]: ../contributing/git-guide.html#fetch-another-contributor-s-branch
|
||||
[self-fetch-pr]: ../contributing/git-guide.html#checkout-a-pull-request-locally
|
||||
[self-push-commits]: ../contributing/git-guide.html#push-your-commits-to-github
|
||||
[self-travisci]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration
|
||||
[self-multiple-computers]: ../contributing/git-guide.html#working-from-multiple-computers
|
||||
[self-git-terms]: ../contributing/git-guide.html#important-git-terms
|
||||
[tools-PR]: #fetch-a-pull-request-and-rebase
|
||||
[images-gui-stage]: _images/zulip-gui-stage.gif
|
||||
[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
|
||||
[edx-howto-rebase-pr]: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request
|
||||
[tig]: http://jonas.nitro.dk/tig/
|
||||
|
|
@ -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,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>
|
||||
|
|
@ -82,14 +82,14 @@ And if you've setup the Zulip development environment on a remote
|
|||
machine, take a look at our tips for
|
||||
[developing remotely][dev-remote].
|
||||
|
||||
[dev-remote]: dev-remote.html
|
||||
[install-direct]: dev-setup-non-vagrant.html#installing-directly-on-ubuntu
|
||||
[install-docker]: dev-setup-non-vagrant.html#using-docker-experimental
|
||||
[install-generic]: dev-setup-non-vagrant.html#installing-manually-on-linux
|
||||
[install-vagrant]: dev-env-first-time-contributors.html
|
||||
[dev-remote]: remote.html
|
||||
[install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu
|
||||
[install-docker]: ../development/setup-advanced.html#using-docker-experimental
|
||||
[install-generic]: ../development/setup-advanced.html#installing-manually-on-linux
|
||||
[install-vagrant]: ../development/setup-vagrant.html
|
||||
[self-install-remote]: #installing-remotely
|
||||
[self-slow-internet]: #slow-internet-connections
|
||||
[configure-proxy]: dev-env-first-time-contributors.html#specifying-a-proxy
|
||||
[using-dev-env]: using-dev-environment.html
|
||||
[testing]: testing.html
|
||||
[travis-ci]: git-guide.html#step-3-configure-travis-ci-continuous-integration
|
||||
[configure-proxy]: ../development/setup-vagrant.html#specifying-a-proxy
|
||||
[using-dev-env]: using.html
|
||||
[testing]: ../testing/testing.html
|
||||
[travis-ci]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration
|
||||
|
|
@ -56,7 +56,7 @@ navigate to `http://<REMOTE_IP>:9991` and you should see something like
|
|||
this screenshot of the Zulip development environment:
|
||||
|
||||
|
||||
environment](../images/zulip-dev.png)
|
||||
|
||||
You can [port
|
||||
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)
|
||||
* [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.
|
||||
|
||||
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]
|
||||
* [Testing][rtd-testing]
|
||||
|
||||
[install-direct]: dev-setup-non-vagrant.html#installing-directly-on-ubuntu
|
||||
[install-generic]: dev-setup-non-vagrant.html#installing-manually-on-linux
|
||||
[install-vagrant]: dev-env-first-time-contributors.html
|
||||
[rtd-git-guide]: git-guide.html
|
||||
[rtd-using-dev-env]: using-dev-environment.html
|
||||
[rtd-testing]: testing.html
|
||||
[install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu
|
||||
[install-generic]: ../development/setup-advanced.html#installing-manually-on-linux
|
||||
[install-vagrant]: ../development/setup-vagrant.html
|
||||
[rtd-git-guide]: ../contributing/git-guide.html
|
||||
[rtd-using-dev-env]: using.html
|
||||
[rtd-testing]: ../testing/testing.html
|
||||
[git-bash]: https://git-for-windows.github.io/
|
||||
[codeanywhere]: https://codeanywhere.com/
|
||||
[img-ca-settings]: images/codeanywhere-settings.png
|
||||
[img-ca-workspace]: images/codeanywhere-workspace.png
|
||||
[img-ca-settings]: ../images/codeanywhere-settings.png
|
||||
[img-ca-workspace]: ../images/codeanywhere-workspace.png
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Zulip development environment setup without Vagrant
|
||||
# Advanced Setup (non-Vagrant)
|
||||
|
||||
Contents:
|
||||
|
||||
|
|
@ -28,7 +28,7 @@ development environment).
|
|||
|
||||
Once you've done the above setup, you can pick up the [documentation
|
||||
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).
|
||||
|
||||
## Installing manually on Linux
|
||||
|
|
@ -411,7 +411,7 @@ docker run -itv $(pwd):/srv/zulip -p 9991:9991 user/zulipdev:v2 \
|
|||
```
|
||||
|
||||
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
|
||||
`start-dockers` automatically runs `tools/run-dev.py` inside the
|
||||
container; you can then visit http://localhost:9991 to connect to your
|
||||
|
|
@ -24,7 +24,7 @@ environment,** check
|
|||
[Troubleshooting and Common Errors](#troubleshooting-and-common-errors). If
|
||||
that doesn't help, please visit
|
||||
[#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
|
||||
[Zulip-devel Google group](https://groups.google.com/forum/#!forum/zulip-devel)
|
||||
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
|
||||
the Zulip development server, and initializes a default test
|
||||
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
|
||||
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)
|
||||
section. If that doesn't help, please visit
|
||||
[#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.
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
|
@ -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
|
||||
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.
|
||||
|
||||
#### Committing and pushing changes with git
|
||||
|
|
@ -507,7 +507,7 @@ After provisioning, you'll want to
|
|||
|
||||
If you run into any trouble, the
|
||||
[#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.
|
||||
|
||||
#### 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:
|
||||
|
||||
* 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
|
||||
group](https://groups.google.com/forum/#!forum/zulip-devel), or
|
||||
* [File an issue](https://github.com/zulip/zulip/issues).
|
||||
|
|
@ -886,7 +886,7 @@ Likely causes are:
|
|||
1. Networking issues
|
||||
2. Insufficient RAM. Check whether you've allotted at least two
|
||||
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
|
||||
the VM.
|
||||
|
||||
|
|
@ -967,7 +967,7 @@ patching file bundler.rb
|
|||
|
||||
#### 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
|
||||
|
||||
|
|
@ -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
|
||||
[vagrant-vmware-fusion-dl]: https://www.vagrantup.com/vmware/
|
||||
[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
|
||||
[rtd-git-guide]: git-guide.html
|
||||
[rtd-testing]: testing.html
|
||||
[rtd-using-dev-env]: using-dev-environment.html
|
||||
[rtd-dev-remote]: dev-remote.html
|
||||
[rtd-git-guide]: ../contributing/git-guide.html
|
||||
[rtd-testing]: ../testing/testing.html
|
||||
[rtd-using-dev-env]: using.html
|
||||
[rtd-dev-remote]: remote.html
|
||||
[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
|
||||
[set-up-git]: git-guide.html#set-up-git
|
||||
[travis-ci]: git-guide.html#step-3-configure-travis-ci-continuous-integration
|
||||
[set-up-git]: ../contributing/git-guide.html#set-up-git
|
||||
[travis-ci]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration
|
||||
|
|
@ -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).
|
||||
|
||||
[django-runserver]: https://docs.djangoproject.com/en/1.8/ref/django-admin/#runserver-port-or-address-port
|
||||
[new-feature-tutorial]: new-feature-tutorial.html
|
||||
[testing-docs]: testing.html
|
||||
[new-feature-tutorial]: ../tutorials/new-feature-tutorial.html
|
||||
[testing-docs]: ../testing/testing.html
|
||||
129
docs/index.rst
129
docs/index.rst
|
|
@ -31,138 +31,67 @@ is your first time here, you may want to start with
|
|||
|
||||
Contents:
|
||||
|
||||
* :ref:`overview`
|
||||
* :ref:`zulip-in-production`
|
||||
* :ref:`development-environment`
|
||||
* :ref:`developer-tutorials`
|
||||
* :ref:`code-contribution-guide`
|
||||
* :ref:`code-testing`
|
||||
* :ref:`subsystem-documentation`
|
||||
* :ref:`Overview <overview>`
|
||||
* :ref:`Zulip in Production <zulip-in-production>`
|
||||
* :ref:`Development Environment <development-environment>`
|
||||
* :ref:`Developer Tutorials <developer-tutorials>`
|
||||
* :ref:`Code Contribution Guide <code-contribution-guide>`
|
||||
* :ref:`Code Testing <code-testing>`
|
||||
* :ref:`Subsystem Documentation <subsystem-documentation>`
|
||||
* :ref:`Translating <translating>`
|
||||
|
||||
.. _overview:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Overview
|
||||
:maxdepth: 3
|
||||
|
||||
readme-symlink
|
||||
contributing
|
||||
architecture-overview
|
||||
directory-structure
|
||||
roadmap
|
||||
changelog
|
||||
overview/index
|
||||
|
||||
.. _zulip-in-production:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Zulip in production
|
||||
:maxdepth: 3
|
||||
|
||||
Production overview <prod>
|
||||
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
|
||||
production/index
|
||||
|
||||
.. _development-environment:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Development environment
|
||||
:maxdepth: 3
|
||||
|
||||
Development environment installation <dev-overview>
|
||||
Recommended setup (Vagrant) <dev-env-first-time-contributors>
|
||||
Advanced setup (non-Vagrant) <dev-setup-non-vagrant>
|
||||
Using the development environment <using-dev-environment>
|
||||
Developing remotely <dev-remote>
|
||||
development/index
|
||||
|
||||
.. _developer-tutorials:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Developer tutorials
|
||||
:maxdepth: 3
|
||||
|
||||
integration-guide
|
||||
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
|
||||
tutorials/index
|
||||
|
||||
.. _code-contribution-guide:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Code contribution guide
|
||||
:maxdepth: 3
|
||||
|
||||
git-guide
|
||||
version-control
|
||||
code-style
|
||||
mypy
|
||||
code-reviewing
|
||||
chat-zulip-org
|
||||
zulipbot-usage
|
||||
accessibility
|
||||
bug-reports
|
||||
contributing/index
|
||||
|
||||
.. _code-testing:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Code testing
|
||||
:maxdepth: 3
|
||||
|
||||
testing
|
||||
linters
|
||||
testing-with-django
|
||||
testing-with-node
|
||||
testing-with-casper
|
||||
travis
|
||||
manual-testing
|
||||
testing/index
|
||||
|
||||
.. _subsystem-documentation:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Subsystem documentation
|
||||
: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
|
||||
translating
|
||||
html-templates
|
||||
client
|
||||
logging
|
||||
typing-indicators
|
||||
release-checklist
|
||||
api-release-checklist
|
||||
swagger-api-docs
|
||||
documentation
|
||||
user-docs
|
||||
subsystems/index
|
||||
|
||||
.. _translating:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
translating/index
|
||||
|
|
|
|||
|
|
@ -1,3 +0,0 @@
|
|||
# Using Docker (experimental)
|
||||
|
||||
Moved to [Advanced setup (Docker)](dev-setup-non-vagrant.html#using-docker-experimental).
|
||||
|
|
@ -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).
|
||||
|
|
@ -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).
|
||||
|
|
@ -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
|
||||
server-side code and the web client, as well as Python API bindings
|
||||
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
|
||||
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
|
||||
members of particular groups (using email domain names or corporate
|
||||
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;
|
||||
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
|
||||
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
|
||||
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
|
||||
|
|
@ -81,7 +81,7 @@ real-time notifications they find irrelevant.
|
|||
Components
|
||||
----------
|
||||
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
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`.
|
||||
|
||||
#### HTML templates, JavaScript, etc.
|
||||
|
|
@ -126,10 +126,10 @@ live-rendering HTML from JavaScript for things like the main message
|
|||
feed.
|
||||
|
||||
For more details on the frontend, see our documentation on
|
||||
[translation](translating.html),
|
||||
[templates](html-templates.html),
|
||||
[directory structure](directory-structure.html), and
|
||||
[the static asset pipeline](front-end-build-process.html).
|
||||
[translation](../translating/translating.html),
|
||||
[templates](../subsystems/html-templates.html),
|
||||
[directory structure](../overview/directory-structure.html), and
|
||||
[the static asset pipeline](../subsystems/front-end-build-process.html).
|
||||
|
||||
[Jinja2]: http://jinja.pocoo.org/
|
||||
[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
|
||||
expensive (in terms of performance) and don't have to be synchronous
|
||||
--- e.g., sending emails or updating analytics. Also see [the queuing
|
||||
guide](queuing.html).
|
||||
guide](../subsystems/queuing.html).
|
||||
|
||||
### 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
|
||||
in `zerver/worker/queue_processors.py`.
|
||||
|
||||
Also see [the queuing guide](queuing.html).
|
||||
Also see [the queuing guide](../subsystems/queuing.html).
|
||||
|
||||
### PostgreSQL
|
||||
|
||||
|
|
@ -99,9 +99,9 @@ Backend and scaling
|
|||
minimizes disruption by running these first, before beginning the
|
||||
user-facing downtime. However, if you'd like to watch the downtime
|
||||
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
|
||||
[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
|
||||
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
|
||||
servers that only have one organization. If you manage a server
|
||||
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
|
||||
be much more intuitive. If you were using the
|
||||
|
|
@ -259,7 +259,7 @@ Zulip apps.
|
|||
Hungarian, Polish, Dutch, Russian, Bulgarian, Portuguese,
|
||||
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
|
||||
[ios-app]: https://itunes.apple.com/us/app/zulip/id1203036395
|
||||
|
||||
|
|
@ -0,0 +1 @@
|
|||
../../CONTRIBUTING.md
|
||||
|
|
@ -4,7 +4,7 @@ This page documents the Zulip directory structure, where to find
|
|||
things, and how to decide where to put a file.
|
||||
|
||||
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.
|
||||
|
||||
### 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/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/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/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/).
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ paths will be familiar to Django developers.
|
|||
|
||||
### 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.
|
||||
|
||||
* `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).
|
||||
|
||||
* `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
|
||||
deactivate a user properly).
|
||||
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
########
|
||||
Overview
|
||||
########
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
readme-symlink
|
||||
contributing
|
||||
architecture-overview
|
||||
directory-structure
|
||||
roadmap
|
||||
changelog
|
||||
|
|
@ -0,0 +1 @@
|
|||
../../README.md
|
||||
|
|
@ -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.
|
||||
|
||||
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.
|
||||
|
||||
First, read the doc section there. (It's short.)
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ default the email backend is enabled.
|
|||
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
|
||||
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.
|
||||
|
||||
### 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)
|
||||
can only receive push notifications from a single Zulip server. We
|
||||
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.
|
||||
Read the linked documentation for instructions on how to register for
|
||||
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
|
||||
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.
|
||||
|
||||
[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.
|
||||
|
||||
Next: [Maintaining and upgrading Zulip in
|
||||
production](prod-maintain-secure-upgrade.html).
|
||||
production](../production/maintain-secure-upgrade.html).
|
||||
|
|
@ -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
|
||||
|
|
@ -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;
|
||||
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!
|
||||
|
|
@ -2,10 +2,10 @@
|
|||
|
||||
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
|
||||
[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
|
||||
[the installation requirements](prod-requirements.html). In short,
|
||||
[the installation requirements](../production/requirements.html). In short,
|
||||
you need:
|
||||
* 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
|
||||
|
|
@ -87,12 +87,12 @@ heading `### MANDATORY SETTINGS`. These settings include:
|
|||
|
||||
- `EMAIL_HOST`, `EMAIL_HOST_USER`: credentials for an outgoing email
|
||||
(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.
|
||||
|
||||
## 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
|
||||
common, and your outgoing email configuration needs to be working in
|
||||
order for you to complete the installation.
|
||||
|
|
@ -119,7 +119,7 @@ in your Zulip installation.
|
|||
## Step 6: Create a Zulip organization and login
|
||||
|
||||
* 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
|
||||
|
|
@ -130,13 +130,13 @@ command](prod-maintain-secure-upgrade.html#management-commands) :
|
|||
new Zulip organization on your server.
|
||||
|
||||
* 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*.
|
||||
|
||||
* Check your email to find the confirmation email and click the
|
||||
link. You'll be prompted to finish setting up your organization and
|
||||
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!
|
||||
|
||||
**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.
|
||||
* [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 further configure your Zulip server](prod-customize.html).
|
||||
* [Learn about maintaining a production Zulip server](prod-maintain-secure-upgrade.html).
|
||||
* [Learn how further configure your Zulip server](customize.html).
|
||||
* [Learn about maintaining a production Zulip server](../production/maintain-secure-upgrade.html).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
|
@ -165,12 +165,12 @@ and can just skip that step.
|
|||
|
||||
* 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 [troubleshooting section](prod-troubleshooting.html) for advice on
|
||||
the [troubleshooting section](troubleshooting.html) for advice on
|
||||
how to debug.
|
||||
|
||||
* If that doesn't help, please visit
|
||||
[#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
|
||||
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
|
||||
|
|
@ -12,7 +12,7 @@ secure Zulip installation, including:
|
|||
|
||||
You may also want to read this related content:
|
||||
|
||||
- [Security Model](security-model.html)
|
||||
- [Security Model](../production/security-model.html)
|
||||
|
||||
## Upgrading
|
||||
|
||||
|
|
@ -229,7 +229,7 @@ lower-priority.
|
|||
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
|
||||
(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
|
||||
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
|
||||
|
|
@ -344,16 +344,16 @@ running Zulip with larger teams (especially >1000 users).
|
|||
* 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
|
||||
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.
|
||||
|
||||
* [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,
|
||||
4 cores, and 80GB of disk. The CPUs are essentially always idle,
|
||||
but the 8GB of RAM is important.
|
||||
|
||||
* 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
|
||||
configuration with two types of servers: application servers
|
||||
(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
|
||||
|
||||
Zulip's security model is discussed in
|
||||
[a separate document](security-model.html).
|
||||
[a separate document](../production/security-model.html).
|
||||
|
||||
## Management commands
|
||||
|
||||
|
|
@ -486,4 +486,4 @@ There are a large number of useful management commands under
|
|||
|
||||
## 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).
|
||||
|
|
@ -28,7 +28,7 @@ follows:
|
|||
|
||||
3. Uncomment the `PUSH_NOTIFICATION_BOUNCER_URL = "https://push.zulipchat.com"`
|
||||
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
|
||||
the line (it won't be there to uncomment).
|
||||
|
||||
|
|
@ -7,7 +7,7 @@ single 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
|
||||
[technically focused article on realms](realms.html) to be useful
|
||||
[technically focused article on realms](../subsystems/realms.html) to be useful
|
||||
reading.
|
||||
|
||||
## Subdomains
|
||||
|
|
@ -35,7 +35,7 @@ things:
|
|||
certificates.
|
||||
* Use `./manage.py generate_realm_creation_link` again to create your
|
||||
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.
|
||||
|
||||
For servers hosting a large number of organizations, like
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
# Zulip in production
|
||||
|
||||
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>.
|
||||
|
||||
If you like what you see, you can set up Zulip for your team by
|
||||
|
|
@ -10,21 +10,21 @@ through how.
|
|||
|
||||
## 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:
|
||||
* a dedicated server or VM, running Ubuntu, with at least 2GB of RAM
|
||||
(or 4GB for a large site);
|
||||
* a valid DNS name and SSL certificates;
|
||||
* 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
|
||||
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.
|
||||
|
||||
## 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
|
||||
a handful of required settings; then create your Zulip organization
|
||||
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
|
||||
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
|
||||
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
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Note that if you just want to play around with Zulip and see what it looks
|
||||
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>.
|
||||
|
||||
## 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
|
||||
disregard our advice and use a server that hosts other services, we
|
||||
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
|
||||
|
||||
|
|
@ -36,7 +36,7 @@ save yourself the work of upgrading in a few months.
|
|||
for organizations with a hundreds of users (active or no).
|
||||
|
||||
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.
|
||||
|
||||
* 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
|
||||
reset, etc.). If you don't have an existing outgoing SMTP solution,
|
||||
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
|
||||
Zulip in production](prod-install.html).
|
||||
Zulip in production](../production/install.html).
|
||||
|
|
@ -37,7 +37,7 @@ announcement).
|
|||
* The preferred way to login to Zulip is using an SSO solution like
|
||||
Google Auth, LDAP, or similar, but Zulip also supports password
|
||||
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.
|
||||
|
||||
### Passwords
|
||||
|
|
@ -6,8 +6,8 @@ supervisorctl](#using-supervisorctl), to learn how to use the
|
|||
Supervisor client to monitor and manage services.
|
||||
|
||||
If you haven't already, now might be a good time to read Zulip's [architectural
|
||||
overview](architecture-overview.html), particularly the
|
||||
[Components](architecture-overview.html#components) section. This will help you
|
||||
overview](../overview/architecture-overview.html), particularly the
|
||||
[Components](../overview/architecture-overview.html#components) section. This will help you
|
||||
understand the many services Zulip uses.
|
||||
|
||||
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
|
||||
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 +0,0 @@
|
|||
../README.md
|
||||
|
|
@ -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:
|
||||
|
||||
* [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
|
||||
* 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:
|
||||
|
||||
* [Using the Development Environment](using-dev-environment.html)
|
||||
* [Testing](testing.html)
|
||||
* [Using the Development Environment](using.html)
|
||||
* [Testing](../testing/testing.html)
|
||||
|
||||
[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/
|
||||
|
|
|
|||
|
|
@ -35,4 +35,4 @@ object as `request.client`.
|
|||
In most integrations, `request.client` is then passed to
|
||||
`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
|
||||
information, see [the webhook walkthrough](webhook-walkthrough.html).
|
||||
information, see [the webhook walkthrough](../tutorials/webhook-walkthrough.html).
|
||||
|
|
@ -33,7 +33,7 @@ document:
|
|||
|
||||
This document focuses almost entirely on the **export** piece. Issues
|
||||
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
|
||||
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
|
||||
|
|
@ -177,7 +177,7 @@ you basically have to solve these problems:
|
|||
Zulip actually supports a bunch of integrations out-of-the-box that
|
||||
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
|
||||
**World Reader**.
|
||||
|
||||
|
|
@ -74,12 +74,12 @@ the backend, but does in JavaScript.
|
|||
|
||||
For the third-party services like Postgres, Redis, Nginx, and RabbitMQ
|
||||
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
|
||||
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
|
||||
[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
|
||||
on specific versions of these packages wherever possible.
|
||||
|
||||
|
|
@ -197,7 +197,7 @@ reasoning here.
|
|||
dependencies in the `yarn.lock` file; `yarn upgrade` updates the
|
||||
`yarn.lock` files.
|
||||
* `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
|
||||
production. Instead, static assets are compiled using our static
|
||||
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
|
||||
have a tool, `tools/setup/build_emoji`, which reformats the emoji data
|
||||
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
|
||||
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
|
||||
|
||||
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
|
||||
emoji, but without the caching (and thus without the
|
||||
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,
|
||||
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
|
||||
versions of Linux from here into `tools/lib/provision.py`.
|
||||
* Production. Our tools for compiling/generating static assets need
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Documentation
|
||||
# Documentation Overview
|
||||
|
||||
Zulip has three major documentation systems:
|
||||
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
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
|
||||
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
|
||||
can reply to missed message emails via email), you might be interested in
|
||||
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
|
||||
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
|
||||
[here](queuing.html).
|
||||
[here](../subsystems/queuing.html).
|
||||
|
||||
## 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 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.
|
||||
|
||||
**Note: The base_image_uri of the images in forwarded emails would be replaced
|
||||
|
|
@ -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
|
||||
order to cache old versions to make provisioning and production
|
||||
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.
|
||||
|
||||
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/unicode/` tree. This is used to serve individual emoji
|
||||
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
|
||||
tree, we currently include all of the emoji in `emoji-map.json`;
|
||||
this means that if you send `:angry_face:`, it won't autocomplete,
|
||||
|
|
@ -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
|
||||
read an example of how a complete feature using this system works,
|
||||
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
|
||||
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,
|
||||
which is ideal for handling a large number of open requests. Details
|
||||
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.
|
||||
The complete system is about 1500 lines of code in `zerver/tornado/`,
|
||||
primarily `zerver/tornado/event_queue.py`.
|
||||
|
|
@ -3,9 +3,9 @@
|
|||
This page documents additional information that may be useful when
|
||||
developing new features for Zulip that require front-end changes,
|
||||
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.
|
||||
|
||||
## Primary build process
|
||||
|
|
@ -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
|
||||
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
|
||||
[events-system]: events-system.html
|
||||
[events-system]: ../subsystems/events-system.html
|
||||
|
|
@ -83,9 +83,9 @@ developers) should be tagged for [translation][].
|
|||
[Jinja2]: http://jinja.pocoo.org/
|
||||
[Handlebars]: http://handlebarsjs.com/
|
||||
[trans]: http://jinja.pocoo.org/docs/dev/templates/#i18n
|
||||
[i18next]: http://i18next.com
|
||||
[official]: http://i18next.com/translate/pluralSimple/
|
||||
[i18next]: https://www.i18next.com
|
||||
[official]: https://www.i18next.com/plurals.html
|
||||
[helpers]: http://handlebarsjs.com/block_helpers.html
|
||||
[jconditionals]: http://jinja.pocoo.org/docs/2.9/templates/#list-of-control-structures
|
||||
[hconditionals]: http://handlebarsjs.com/block_helpers.html
|
||||
[translation]: translating.html
|
||||
[translation]: ../translating/translating.html
|
||||
|
|
@ -8,7 +8,7 @@ main third-party CSS library.
|
|||
|
||||
Zulip currently does not use any CSS preprocessors, and is organized
|
||||
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`.
|
||||
|
||||
The CSS files are:
|
||||
|
|
@ -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
|
||||
|
|
@ -167,7 +167,7 @@ and report to the server the following whenever a message is sent:
|
|||
* Whether the message was locally echoed.
|
||||
* If so, whether there was a disparity between the echoed content and
|
||||
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`.
|
||||
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# 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
|
||||
their Google accounts or GitHub accounts, using the OAuth protocol.
|
||||
|
||||
|
|
@ -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!
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -6,7 +6,7 @@ user documentation as an organization (the name "realm" comes from
|
|||
[Kerberos](https://web.mit.edu/kerberos/)).
|
||||
|
||||
The
|
||||
[production docs on multiple realms](prod-multiple-organizations.html)
|
||||
[production docs on multiple realms](../production/multiple-organizations.html)
|
||||
are likely also relevant reading.
|
||||
|
||||
## Creating Realms
|
||||
|
|
@ -52,7 +52,7 @@ job.
|
|||
|
||||
We also recommend upgrading to at least Zulip 1.7, since older Zulip
|
||||
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.
|
||||
|
||||
### Working With Subdomains In Development Environment
|
||||
|
|
@ -3,7 +3,7 @@
|
|||
Zulip uses the [standard Django system for doing schema
|
||||
migrations](https://docs.djangoproject.com/en/1.10/topics/migrations/).
|
||||
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
|
||||
migrations.
|
||||
|
|
@ -30,7 +30,7 @@ migrations.
|
|||
fix this, you can either run `./tools/renumber-migrations` which
|
||||
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
|
||||
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.
|
||||
|
||||
* **Atomicity**. By default, each Django migration is run atomically
|
||||
|
|
@ -143,4 +143,4 @@ replaced with realm settings:
|
|||
server, and in the realm settings indicating which methods the realm
|
||||
administrator wants to allow users to login with.
|
||||
|
||||
[doc-newfeat]: new-feature-tutorial.html
|
||||
[doc-newfeat]: ../tutorials/new-feature-tutorial.html
|
||||
|
|
@ -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
|
||||
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,
|
||||
which minimizes the possibility of backend bugs and gives clients
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# General user guide documentation
|
||||
# General User Guide Documentation
|
||||
|
||||
Our goal is for Zulip to have complete, high-quality user-appealing
|
||||
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
|
||||
describing a related task.
|
||||
|
||||
|
||||
|
||||
|
||||
You can also conclude your documentation with some final notes.
|
||||
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
############
|
||||
Code Testing
|
||||
############
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
testing
|
||||
linters
|
||||
testing-with-django
|
||||
testing-with-node
|
||||
testing-with-casper
|
||||
travis
|
||||
manual-testing
|
||||
|
|
@ -11,7 +11,7 @@ but for other files, we are quite thorough about checking semantic
|
|||
correctness.
|
||||
|
||||
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.
|
||||
|
||||
We borrow some open source tools for much of our linting, and the links
|
||||
|
|
@ -56,7 +56,7 @@ the other lint checks.
|
|||
|
||||
## 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
|
||||
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.
|
||||
|
|
@ -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
|
||||
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
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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
|
||||
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`.
|
||||
|
||||
|
|
@ -254,7 +254,7 @@ from Django as well as our own custom helpers. Here is an example:
|
|||
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
|
|
@ -5,10 +5,10 @@
|
|||
Zulip has a full test suite that includes many components. The most
|
||||
important components are documented in depth in their own sections:
|
||||
|
||||
- [Django](testing-with-django.html): backend Python tests
|
||||
- [Casper](testing-with-casper.html): end-to-end UI tests
|
||||
- [Node](testing-with-node.html): unit tests for JS front end code
|
||||
- [Linters](linters.html): Our parallel linter suite
|
||||
- [Django](../testing/testing-with-django.html): backend Python tests
|
||||
- [Casper](../testing/testing-with-casper.html): end-to-end UI tests
|
||||
- [Node](../testing/testing-with-node.html): unit tests for JS front end code
|
||||
- [Linters](../testing/linters.html): Our parallel linter suite
|
||||
- [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
|
||||
|
|
@ -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
|
||||
response should be used by the tests for every outgoing HTTP (or other
|
||||
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
|
||||
examples throughout the codebase.
|
||||
|
||||
|
|
@ -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
|
||||
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
|
||||
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
#################
|
||||
Translating Zulip
|
||||
#################
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
translating
|
||||
chinese
|
||||
french
|
||||
german
|
||||
polish
|
||||
russian
|
||||
spanish
|
||||
|
|
@ -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
|
||||
Zulip friendly and usable.
|
||||
|
||||
# Common translations
|
||||
|
||||
## Special terms used in Zulip
|
||||
|
||||
**customization**: personalizacja, *kastomizacja* could be too awkward
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Translating Zulip
|
||||
# Translation Guidelines
|
||||
|
||||
To make Zulip even better for users around the world, the Zulip UI is
|
||||
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
|
||||
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
|
||||
[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
|
||||
|
|
@ -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
|
||||
with what your work.
|
||||
|
||||
### Capitalization
|
||||
## Capitalization
|
||||
|
||||
We expect that all the English translatable strings in Zulip are
|
||||
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:
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -132,7 +132,7 @@ Some useful tips for your translating journey:
|
|||
|
||||
- When in doubt, ask for context 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
|
||||
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
|
||||
|
||||
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
|
||||
`tx pull -a --mode=developer` command (it will require some
|
||||
|
|
@ -386,11 +386,11 @@ organizations from the command line.
|
|||
[Jinja2]: http://jinja.pocoo.org/
|
||||
[Handlebars]: http://handlebarsjs.com/
|
||||
[trans]: http://jinja.pocoo.org/docs/dev/templates/#i18n
|
||||
[i18next]: http://i18next.com
|
||||
[official]: http://i18next.com/translate/pluralSimple/
|
||||
[i18next]: https://www.i18next.com
|
||||
[official]: https://www.i18next.com/plurals.html
|
||||
[unescape]: https://www.i18next.com/interpolation.html#unescape
|
||||
[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
|
||||
[transifexrc]: https://docs.transifex.com/client/client-configuration#transifexrc
|
||||
[html-templates]: html-templates.html
|
||||
[html-templates]: ../subsystems/html-templates.html
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue