diff --git a/docs/brief-install-vagrant-dev.md b/docs/brief-install-vagrant-dev.md index 3e799ae0cb..a1c6d21925 100644 --- a/docs/brief-install-vagrant-dev.md +++ b/docs/brief-install-vagrant-dev.md @@ -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 diff --git a/docs/conf.py b/docs/conf.py index 0a553ed5c1..ee9ea88946 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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. diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 120000 index 44fcc63439..0000000000 --- a/docs/contributing.md +++ /dev/null @@ -1 +0,0 @@ -../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/accessibility.md b/docs/contributing/accessibility.md similarity index 100% rename from docs/accessibility.md rename to docs/contributing/accessibility.md diff --git a/docs/bug-reports.md b/docs/contributing/bug-reports.md similarity index 100% rename from docs/bug-reports.md rename to docs/contributing/bug-reports.md diff --git a/docs/chat-zulip-org.md b/docs/contributing/chat-zulip-org.md similarity index 99% rename from docs/chat-zulip-org.md rename to docs/contributing/chat-zulip-org.md index b1a0519879..befcc0e38f 100644 --- a/docs/chat-zulip-org.md +++ b/docs/contributing/chat-zulip-org.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, diff --git a/docs/code-reviewing.md b/docs/contributing/code-reviewing.md similarity index 95% rename from docs/code-reviewing.md rename to docs/contributing/code-reviewing.md index 20ed20d33c..cba8816866 100644 --- a/docs/code-reviewing.md +++ b/docs/contributing/code-reviewing.md @@ -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 diff --git a/docs/code-style.md b/docs/contributing/code-style.md similarity index 98% rename from docs/code-style.md rename to docs/contributing/code-style.md index 80babad7e2..857ff4adf6 100644 --- a/docs/code-style.md +++ b/docs/contributing/code-style.md @@ -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. diff --git a/docs/git-guide.md b/docs/contributing/git-guide.md similarity index 95% rename from docs/git-guide.md rename to docs/contributing/git-guide.md index f66ea51afe..f9e8f3e736 100644 --- a/docs/git-guide.md +++ b/docs/contributing/git-guide.md @@ -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/ diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 0000000000..34de4a38ba --- /dev/null +++ b/docs/contributing/index.rst @@ -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 diff --git a/docs/mypy.md b/docs/contributing/mypy.md similarity index 100% rename from docs/mypy.md rename to docs/contributing/mypy.md diff --git a/docs/version-control.md b/docs/contributing/version-control.md similarity index 100% rename from docs/version-control.md rename to docs/contributing/version-control.md diff --git a/docs/zulipbot-usage.md b/docs/contributing/zulipbot-usage.md similarity index 100% rename from docs/zulipbot-usage.md rename to docs/contributing/zulipbot-usage.md diff --git a/docs/development/index.rst b/docs/development/index.rst new file mode 100644 index 0000000000..21034672ad --- /dev/null +++ b/docs/development/index.rst @@ -0,0 +1,12 @@ +####################### +Development Environment +####################### + +.. toctree:: + :maxdepth: 3 + + Development environment installation + Recommended setup (Vagrant) + Advanced Setup (non-Vagrant) + Using the development environment + Developing remotely diff --git a/docs/dev-overview.md b/docs/development/overview.md similarity index 86% rename from docs/dev-overview.md rename to docs/development/overview.md index 20c67127b0..c974553845 100644 --- a/docs/dev-overview.md +++ b/docs/development/overview.md @@ -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 diff --git a/docs/dev-remote.md b/docs/development/remote.md similarity index 91% rename from docs/dev-remote.md rename to docs/development/remote.md index f0b230b000..3027869c59 100644 --- a/docs/dev-remote.md +++ b/docs/development/remote.md @@ -56,7 +56,7 @@ navigate to `http://:9991` and you should see something like this screenshot of the Zulip development environment: ![Image of Zulip development -environment](images/zulip-dev.png) +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 diff --git a/docs/dev-setup-non-vagrant.md b/docs/development/setup-advanced.md similarity index 98% rename from docs/dev-setup-non-vagrant.md rename to docs/development/setup-advanced.md index 164ac43319..e01c375f5d 100644 --- a/docs/dev-setup-non-vagrant.md +++ b/docs/development/setup-advanced.md @@ -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 diff --git a/docs/dev-env-first-time-contributors.md b/docs/development/setup-vagrant.md similarity index 97% rename from docs/dev-env-first-time-contributors.md rename to docs/development/setup-vagrant.md index ba67528eab..7f0dbd5346 100644 --- a/docs/dev-env-first-time-contributors.md +++ b/docs/development/setup-vagrant.md @@ -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 in the browser on your main machine. 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. 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 diff --git a/docs/using-dev-environment.md b/docs/development/using.md similarity index 96% rename from docs/using-dev-environment.md rename to docs/development/using.md index a4beedf1a4..ff34d898fb 100644 --- a/docs/using-dev-environment.md +++ b/docs/development/using.md @@ -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 diff --git a/docs/index.rst b/docs/index.rst index a7a130062e..9d568f0ea3 100644 --- a/docs/index.rst +++ b/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 ` +* :ref:`Zulip in Production ` +* :ref:`Development Environment ` +* :ref:`Developer Tutorials ` +* :ref:`Code Contribution Guide ` +* :ref:`Code Testing ` +* :ref:`Subsystem Documentation ` +* :ref:`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-requirements - Installing a production server - 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 - Recommended setup (Vagrant) - Advanced setup (non-Vagrant) - Using the development environment - Developing remotely + 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 diff --git a/docs/install-docker-dev.md b/docs/install-docker-dev.md deleted file mode 100644 index 98d357a4d0..0000000000 --- a/docs/install-docker-dev.md +++ /dev/null @@ -1,3 +0,0 @@ -# Using Docker (experimental) - -Moved to [Advanced setup (Docker)](dev-setup-non-vagrant.html#using-docker-experimental). diff --git a/docs/install-generic-unix-dev.md b/docs/install-generic-unix-dev.md deleted file mode 100644 index 6104174a97..0000000000 --- a/docs/install-generic-unix-dev.md +++ /dev/null @@ -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). diff --git a/docs/install-ubuntu-without-vagrant-dev.md b/docs/install-ubuntu-without-vagrant-dev.md deleted file mode 100644 index 6c4dc4f15f..0000000000 --- a/docs/install-ubuntu-without-vagrant-dev.md +++ /dev/null @@ -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). diff --git a/docs/architecture-overview.md b/docs/overview/architecture-overview.md similarity index 95% rename from docs/architecture-overview.md rename to docs/overview/architecture-overview.md index 5ac7b457f5..112946f7a3 100644 --- a/docs/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -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 ---------- - ![architecture-simple](images/architecture_simple.png) + ![architecture-simple](../images/architecture_simple.png) ### 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 diff --git a/docs/changelog.md b/docs/overview/changelog.md similarity index 99% rename from docs/changelog.md rename to docs/overview/changelog.md index 2ec7b66ddb..a2813b5f9e 100644 --- a/docs/changelog.md +++ b/docs/overview/changelog.md @@ -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 diff --git a/docs/overview/contributing.md b/docs/overview/contributing.md new file mode 120000 index 0000000000..f939e75f21 --- /dev/null +++ b/docs/overview/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/directory-structure.md b/docs/overview/directory-structure.md similarity index 92% rename from docs/directory-structure.md rename to docs/overview/directory-structure.md index 6ecac2e76c..fccdca854d 100644 --- a/docs/directory-structure.md +++ b/docs/overview/directory-structure.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). diff --git a/docs/overview/index.rst b/docs/overview/index.rst new file mode 100644 index 0000000000..8171773c09 --- /dev/null +++ b/docs/overview/index.rst @@ -0,0 +1,13 @@ +######## +Overview +######## + +.. toctree:: + :maxdepth: 3 + + readme-symlink + contributing + architecture-overview + directory-structure + roadmap + changelog diff --git a/docs/overview/readme-symlink.md b/docs/overview/readme-symlink.md new file mode 120000 index 0000000000..fe84005413 --- /dev/null +++ b/docs/overview/readme-symlink.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/docs/roadmap.md b/docs/overview/roadmap.md similarity index 100% rename from docs/roadmap.md rename to docs/overview/roadmap.md diff --git a/docs/password-strength.md b/docs/password-strength.md index bd44d062c7..6ff57f1f3f 100644 --- a/docs/password-strength.md +++ b/docs/password-strength.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.) diff --git a/docs/prod-authentication-methods.md b/docs/production/authentication-methods.md similarity index 100% rename from docs/prod-authentication-methods.md rename to docs/production/authentication-methods.md diff --git a/docs/prod-customize.md b/docs/production/customize.md similarity index 93% rename from docs/prod-customize.md rename to docs/production/customize.md index e3e12f79c9..a5d8af53a4 100644 --- a/docs/prod-customize.md +++ b/docs/production/customize.md @@ -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). diff --git a/docs/prod-email.md b/docs/production/email.md similarity index 100% rename from docs/prod-email.md rename to docs/production/email.md diff --git a/docs/expensive-migrations.md b/docs/production/expensive-migrations.md similarity index 100% rename from docs/expensive-migrations.md rename to docs/production/expensive-migrations.md diff --git a/docs/production/index.rst b/docs/production/index.rst new file mode 100644 index 0000000000..981c167bac --- /dev/null +++ b/docs/production/index.rst @@ -0,0 +1,17 @@ +################### +Zulip in Production +################### + +.. toctree:: + :maxdepth: 3 + + Production overview + requirements + Installing a production server + troubleshooting + customize + mobile-push-notifications + maintain-secure-upgrade + security-model + authentication-methods + postgres diff --git a/docs/prod-install-existing-server.md b/docs/production/install-existing-server.md similarity index 97% rename from docs/prod-install-existing-server.md rename to docs/production/install-existing-server.md index ffd0e681fc..5febd7a832 100644 --- a/docs/prod-install-existing-server.md +++ b/docs/production/install-existing-server.md @@ -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! diff --git a/docs/prod-install.md b/docs/production/install.md similarity index 88% rename from docs/prod-install.md rename to docs/production/install.md index 36e5af3d74..6f16336616 100644 --- a/docs/prod-install.md +++ b/docs/production/install.md @@ -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 diff --git a/docs/prod-maintain-secure-upgrade.md b/docs/production/maintain-secure-upgrade.md similarity index 97% rename from docs/prod-maintain-secure-upgrade.md rename to docs/production/maintain-secure-upgrade.md index a42c46746b..a06be65394 100644 --- a/docs/prod-maintain-secure-upgrade.md +++ b/docs/production/maintain-secure-upgrade.md @@ -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). diff --git a/docs/prod-mobile-push-notifications.md b/docs/production/mobile-push-notifications.md similarity index 98% rename from docs/prod-mobile-push-notifications.md rename to docs/production/mobile-push-notifications.md index 450e311726..f4b5900ab8 100644 --- a/docs/prod-mobile-push-notifications.md +++ b/docs/production/mobile-push-notifications.md @@ -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). diff --git a/docs/prod-multiple-organizations.md b/docs/production/multiple-organizations.md similarity index 95% rename from docs/prod-multiple-organizations.md rename to docs/production/multiple-organizations.md index ce29dd4264..fd4c9b7212 100644 --- a/docs/prod-multiple-organizations.md +++ b/docs/production/multiple-organizations.md @@ -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 diff --git a/docs/prod.md b/docs/production/overview.md similarity index 65% rename from docs/prod.md rename to docs/production/overview.md index 62024b5907..2b162efdef 100644 --- a/docs/prod.md +++ b/docs/production/overview.md @@ -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 . 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 diff --git a/docs/prod-postgres.md b/docs/production/postgres.md similarity index 100% rename from docs/prod-postgres.md rename to docs/production/postgres.md diff --git a/docs/prod-requirements.md b/docs/production/requirements.md similarity index 90% rename from docs/prod-requirements.md rename to docs/production/requirements.md index 57fb91428c..125f6f44d1 100644 --- a/docs/prod-requirements.md +++ b/docs/production/requirements.md @@ -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 . ## 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). diff --git a/docs/security-model.md b/docs/production/security-model.md similarity index 99% rename from docs/security-model.md rename to docs/production/security-model.md index eeceff3682..dbc2d2a24d 100644 --- a/docs/security-model.md +++ b/docs/production/security-model.md @@ -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 diff --git a/docs/ssl-certificates.md b/docs/production/ssl-certificates.md similarity index 100% rename from docs/ssl-certificates.md rename to docs/production/ssl-certificates.md diff --git a/docs/prod-troubleshooting.md b/docs/production/troubleshooting.md similarity index 96% rename from docs/prod-troubleshooting.md rename to docs/production/troubleshooting.md index ab4f9ad364..5406fd7f1d 100644 --- a/docs/prod-troubleshooting.md +++ b/docs/production/troubleshooting.md @@ -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) diff --git a/docs/readme-symlink.md b/docs/readme-symlink.md deleted file mode 120000 index 32d46ee883..0000000000 --- a/docs/readme-symlink.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/docs/request-remote-dev.md b/docs/request-remote-dev.md index cc488f6066..68ce0b8d78 100644 --- a/docs/request-remote-dev.md +++ b/docs/request-remote-dev.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/ diff --git a/docs/analytics.md b/docs/subsystems/analytics.md similarity index 100% rename from docs/analytics.md rename to docs/subsystems/analytics.md diff --git a/docs/api-release-checklist.md b/docs/subsystems/api-release-checklist.md similarity index 100% rename from docs/api-release-checklist.md rename to docs/subsystems/api-release-checklist.md diff --git a/docs/client.md b/docs/subsystems/client.md similarity index 95% rename from docs/client.md rename to docs/subsystems/client.md index 7d8931e493..5d0552d1ad 100644 --- a/docs/client.md +++ b/docs/subsystems/client.md @@ -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). diff --git a/docs/conversion.md b/docs/subsystems/conversion.md similarity index 99% rename from docs/conversion.md rename to docs/subsystems/conversion.md index 32829e6690..401d71d9b7 100644 --- a/docs/conversion.md +++ b/docs/subsystems/conversion.md @@ -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 diff --git a/docs/custom-apps.md b/docs/subsystems/custom-apps.md similarity index 99% rename from docs/custom-apps.md rename to docs/subsystems/custom-apps.md index de0f3b289f..d9241182df 100644 --- a/docs/custom-apps.md +++ b/docs/subsystems/custom-apps.md @@ -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**. diff --git a/docs/dependencies.md b/docs/subsystems/dependencies.md similarity index 96% rename from docs/dependencies.md rename to docs/subsystems/dependencies.md index 1e04906a06..c2fd139562 100644 --- a/docs/dependencies.md +++ b/docs/subsystems/dependencies.md @@ -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 diff --git a/docs/documentation.md b/docs/subsystems/documentation.md similarity index 99% rename from docs/documentation.md rename to docs/subsystems/documentation.md index 26eca8d3bc..be5df6fd23 100644 --- a/docs/documentation.md +++ b/docs/subsystems/documentation.md @@ -1,4 +1,4 @@ -# Documentation +# Documentation Overview Zulip has three major documentation systems: diff --git a/docs/email.md b/docs/subsystems/email.md similarity index 95% rename from docs/email.md rename to docs/subsystems/email.md index 9424ed0973..2349c70b83 100644 --- a/docs/email.md +++ b/docs/subsystems/email.md @@ -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 diff --git a/docs/emoji.md b/docs/subsystems/emoji.md similarity index 96% rename from docs/emoji.md rename to docs/subsystems/emoji.md index 095ab8173f..c14cda4170 100644 --- a/docs/emoji.md +++ b/docs/subsystems/emoji.md @@ -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, diff --git a/docs/events-system.md b/docs/subsystems/events-system.md similarity index 98% rename from docs/events-system.md rename to docs/subsystems/events-system.md index a2cc62d878..4a787443d9 100644 --- a/docs/events-system.md +++ b/docs/subsystems/events-system.md @@ -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`. diff --git a/docs/front-end-build-process.md b/docs/subsystems/front-end-build-process.md similarity index 97% rename from docs/front-end-build-process.md rename to docs/subsystems/front-end-build-process.md index 36c1b0f3dc..a9610d56df 100644 --- a/docs/front-end-build-process.md +++ b/docs/subsystems/front-end-build-process.md @@ -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 diff --git a/docs/full-text-search.md b/docs/subsystems/full-text-search.md similarity index 100% rename from docs/full-text-search.md rename to docs/subsystems/full-text-search.md diff --git a/docs/hashchange-system.md b/docs/subsystems/hashchange-system.md similarity index 98% rename from docs/hashchange-system.md rename to docs/subsystems/hashchange-system.md index 34ab95b491..214a690b89 100644 --- a/docs/hashchange-system.md +++ b/docs/subsystems/hashchange-system.md @@ -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 diff --git a/docs/hotspots.md b/docs/subsystems/hotspots.md similarity index 100% rename from docs/hotspots.md rename to docs/subsystems/hotspots.md diff --git a/docs/html-templates.md b/docs/subsystems/html-templates.md similarity index 96% rename from docs/html-templates.md rename to docs/subsystems/html-templates.md index 0d68fbbd8d..50576b7091 100644 --- a/docs/html-templates.md +++ b/docs/subsystems/html-templates.md @@ -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 diff --git a/docs/html_css.md b/docs/subsystems/html_css.md similarity index 96% rename from docs/html_css.md rename to docs/subsystems/html_css.md index 9c05f41ed3..0fec825365 100644 --- a/docs/html_css.md +++ b/docs/subsystems/html_css.md @@ -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: diff --git a/docs/subsystems/index.rst b/docs/subsystems/index.rst new file mode 100644 index 0000000000..dd85a3b014 --- /dev/null +++ b/docs/subsystems/index.rst @@ -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 diff --git a/docs/input-pills.md b/docs/subsystems/input-pills.md similarity index 100% rename from docs/input-pills.md rename to docs/subsystems/input-pills.md diff --git a/docs/logging.md b/docs/subsystems/logging.md similarity index 99% rename from docs/logging.md rename to docs/subsystems/logging.md index 1faac0acc0..9c579d092a 100644 --- a/docs/logging.md +++ b/docs/subsystems/logging.md @@ -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`. diff --git a/docs/management-commands.md b/docs/subsystems/management-commands.md similarity index 100% rename from docs/management-commands.md rename to docs/subsystems/management-commands.md diff --git a/docs/markdown.md b/docs/subsystems/markdown.md similarity index 100% rename from docs/markdown.md rename to docs/subsystems/markdown.md diff --git a/docs/oauth.md b/docs/subsystems/oauth.md similarity index 96% rename from docs/oauth.md rename to docs/subsystems/oauth.md index f9252752b0..d7e99936f3 100644 --- a/docs/oauth.md +++ b/docs/subsystems/oauth.md @@ -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. diff --git a/docs/pointer.md b/docs/subsystems/pointer.md similarity index 98% rename from docs/pointer.md rename to docs/subsystems/pointer.md index 44c9b5305d..866ecc8de2 100644 --- a/docs/pointer.md +++ b/docs/subsystems/pointer.md @@ -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 diff --git a/docs/queuing.md b/docs/subsystems/queuing.md similarity index 100% rename from docs/queuing.md rename to docs/subsystems/queuing.md diff --git a/docs/realms.md b/docs/subsystems/realms.md similarity index 95% rename from docs/realms.md rename to docs/subsystems/realms.md index 3ecb360886..56ee3bb8c1 100644 --- a/docs/realms.md +++ b/docs/subsystems/realms.md @@ -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 diff --git a/docs/release-checklist.md b/docs/subsystems/release-checklist.md similarity index 100% rename from docs/release-checklist.md rename to docs/subsystems/release-checklist.md diff --git a/docs/schema-migrations.md b/docs/subsystems/schema-migrations.md similarity index 97% rename from docs/schema-migrations.md rename to docs/subsystems/schema-migrations.md index 7b2bd2e556..09a1dd1884 100644 --- a/docs/schema-migrations.md +++ b/docs/subsystems/schema-migrations.md @@ -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 diff --git a/docs/settings.md b/docs/subsystems/settings.md similarity index 99% rename from docs/settings.md rename to docs/subsystems/settings.md index b80118070d..1ee0b17ee7 100644 --- a/docs/settings.md +++ b/docs/subsystems/settings.md @@ -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 diff --git a/docs/swagger-api-docs.md b/docs/subsystems/swagger-api-docs.md similarity index 100% rename from docs/swagger-api-docs.md rename to docs/subsystems/swagger-api-docs.md diff --git a/docs/typing-indicators.md b/docs/subsystems/typing-indicators.md similarity index 99% rename from docs/typing-indicators.md rename to docs/subsystems/typing-indicators.md index b2870b0386..2b9686fecf 100644 --- a/docs/typing-indicators.md +++ b/docs/subsystems/typing-indicators.md @@ -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 diff --git a/docs/unread_messages.md b/docs/subsystems/unread_messages.md similarity index 100% rename from docs/unread_messages.md rename to docs/subsystems/unread_messages.md diff --git a/docs/user-docs.md b/docs/subsystems/user-docs.md similarity index 99% rename from docs/user-docs.md rename to docs/subsystems/user-docs.md index e7fc1a33b7..2c7f72fc88 100644 --- a/docs/user-docs.md +++ b/docs/subsystems/user-docs.md @@ -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. -![Feature](/static/images/help/feature.png) +![Feature](../static/images/help/feature.png) You can also conclude your documentation with some final notes. diff --git a/docs/testing/index.rst b/docs/testing/index.rst new file mode 100644 index 0000000000..28dea1f8c9 --- /dev/null +++ b/docs/testing/index.rst @@ -0,0 +1,14 @@ +############ +Code Testing +############ + +.. toctree:: + :maxdepth: 3 + + testing + linters + testing-with-django + testing-with-node + testing-with-casper + travis + manual-testing diff --git a/docs/linters.md b/docs/testing/linters.md similarity index 95% rename from docs/linters.md rename to docs/testing/linters.md index f9b541c350..d7106e2c34 100644 --- a/docs/linters.md +++ b/docs/testing/linters.md @@ -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`. diff --git a/docs/manual-testing.md b/docs/testing/manual-testing.md similarity index 100% rename from docs/manual-testing.md rename to docs/testing/manual-testing.md diff --git a/docs/testing-with-casper.md b/docs/testing/testing-with-casper.md similarity index 100% rename from docs/testing-with-casper.md rename to docs/testing/testing-with-casper.md diff --git a/docs/testing-with-django.md b/docs/testing/testing-with-django.md similarity index 98% rename from docs/testing-with-django.md rename to docs/testing/testing-with-django.md index 706acf69a0..2bcd2b4c7d 100644 --- a/docs/testing-with-django.md +++ b/docs/testing/testing-with-django.md @@ -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 diff --git a/docs/testing-with-node.md b/docs/testing/testing-with-node.md similarity index 100% rename from docs/testing-with-node.md rename to docs/testing/testing-with-node.md diff --git a/docs/testing.md b/docs/testing/testing.md similarity index 95% rename from docs/testing.md rename to docs/testing/testing.md index 0c503b0b54..e156f6d555 100644 --- a/docs/testing.md +++ b/docs/testing/testing.md @@ -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. diff --git a/docs/travis.md b/docs/testing/travis.md similarity index 98% rename from docs/travis.md rename to docs/testing/travis.md index d03437c4e9..c8382d41a6 100644 --- a/docs/travis.md +++ b/docs/testing/travis.md @@ -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 diff --git a/docs/chinese.md b/docs/translating/chinese.md similarity index 100% rename from docs/chinese.md rename to docs/translating/chinese.md diff --git a/docs/french.md b/docs/translating/french.md similarity index 100% rename from docs/french.md rename to docs/translating/french.md diff --git a/docs/german.md b/docs/translating/german.md similarity index 100% rename from docs/german.md rename to docs/translating/german.md diff --git a/docs/translating/index.rst b/docs/translating/index.rst new file mode 100644 index 0000000000..77a36d4266 --- /dev/null +++ b/docs/translating/index.rst @@ -0,0 +1,14 @@ +################# +Translating Zulip +################# + +.. toctree:: + :maxdepth: 3 + + translating + chinese + french + german + polish + russian + spanish diff --git a/docs/polish.md b/docs/translating/polish.md similarity index 99% rename from docs/polish.md rename to docs/translating/polish.md index 55a18c604c..69c01cd673 100644 --- a/docs/polish.md +++ b/docs/translating/polish.md @@ -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 diff --git a/docs/russian.md b/docs/translating/russian.md similarity index 100% rename from docs/russian.md rename to docs/translating/russian.md diff --git a/docs/spanish.md b/docs/translating/spanish.md similarity index 100% rename from docs/spanish.md rename to docs/translating/spanish.md diff --git a/docs/translating.md b/docs/translating/translating.md similarity index 96% rename from docs/translating.md rename to docs/translating/translating.md index ad0d15ab3d..dc46d8c8cb 100644 --- a/docs/translating.md +++ b/docs/translating/translating.md @@ -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 diff --git a/docs/fixing-commits.md b/docs/tutorials/fixing-commits.md similarity index 100% rename from docs/fixing-commits.md rename to docs/tutorials/fixing-commits.md diff --git a/docs/git-cheat-sheet-detailed.md b/docs/tutorials/git-cheat-sheet-detailed.md similarity index 100% rename from docs/git-cheat-sheet-detailed.md rename to docs/tutorials/git-cheat-sheet-detailed.md diff --git a/docs/git-cheat-sheet.md b/docs/tutorials/git-cheat-sheet.md similarity index 100% rename from docs/git-cheat-sheet.md rename to docs/tutorials/git-cheat-sheet.md diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 0000000000..c01ec555e7 --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,20 @@ +################### +Developer Tutorials +################### + +.. toctree:: + :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 diff --git a/docs/integration-docs-guide.md b/docs/tutorials/integration-docs-guide.md similarity index 100% rename from docs/integration-docs-guide.md rename to docs/tutorials/integration-docs-guide.md diff --git a/docs/integration-guide.md b/docs/tutorials/integration-guide.md similarity index 96% rename from docs/integration-guide.md rename to docs/tutorials/integration-guide.md index a7d966aeef..a10af258c9 100644 --- a/docs/integration-guide.md +++ b/docs/tutorials/integration-guide.md @@ -19,7 +19,7 @@ On this page you'll find: separate page. A detailed walkthrough of a simple "Hello World" integration can be -found in the [webhook walkthrough](webhook-walkthrough.html). +found in the [webhook walkthrough](../tutorials/webhook-walkthrough.html). Contributions to this guide are very welcome, so if you run into any issues following these instructions or come up with any tips or tools @@ -99,7 +99,7 @@ New Zulip webhook integrations can take just a few hours to write, including tests and documentation, if you use the right process. **For detailed instructions, check out the ["Hello World" webhook walkthrough]( -webhook-walkthrough.html)**. +../tutorials/webhook-walkthrough.html)**. For a quick guide, read on. @@ -130,7 +130,7 @@ For a quick guide, read on. test-backend zerver/webhooks/pagerduty/ ``` - See [this guide](testing.html) for more details on the Zulip test + See [this guide](../testing/testing.html) for more details on the Zulip test runner. * Once you've gotten your webhook working and passing a test, capture @@ -159,13 +159,13 @@ for a webhook named 'MyWebHook'. integration](integration-docs-guide.html) for details. * `zerver/webhooks/mywebhook/fixtures/messagetype.json`: Sample json payload data used by tests. Add one fixture file per type of message supported by your - integration. See [Testing and writing tests](testing.html) for details. + integration. See [Testing and writing tests](../testing/testing.html) for details. * `zerver/webhooks/mywebhook/__init__.py`: Empty file that is obligatory part of every python package. Remember to `git add` it. * `zerver/webhooks/mywebhook/view.py`: Includes the main webhook integration function including any needed helper functions. * `zerver/webhooks/mywebhook/tests.py`: Add tests for your - webbook. See [Testing and writing tests](testing.html) for details. + webbook. See [Testing and writing tests](../testing/testing.html) for details. * `zerver/webhooks/mywebhook/doc.html`: Add end-user documentation. See [Documenting your integration](integration-docs-guide.html) for details. diff --git a/docs/life-of-a-request.md b/docs/tutorials/life-of-a-request.md similarity index 97% rename from docs/life-of-a-request.md rename to docs/tutorials/life-of-a-request.md index d1a7fc08e5..f040058c4d 100644 --- a/docs/life-of-a-request.md +++ b/docs/tutorials/life-of-a-request.md @@ -18,7 +18,7 @@ itself for static content). In development, `tools/run-dev.py` fills the role of nginx. Static files are in your git checkout under `static`, and are served unminified. -## Nginx secures traffic with [SSL](prod-install.html) +## Nginx secures traffic with [SSL](../production/install.html) If you visit your Zulip server in your browser and discover that your traffic isn't being properly encrypted, an [nginx misconfiguration][nginx-config] is the @@ -47,7 +47,7 @@ location /static/ { ## Nginx routes other requests [between django and tornado][tornado-django] -[tornado-django]: architecture-overview.html?highlight=tornado#django-and-tornado +[tornado-django]: ../overview/architecture-overview.html?highlight=tornado#django-and-tornado All our connected clients hold open long-polling connections so that they can receive events (messages, presence notifications, and so on) in @@ -63,7 +63,7 @@ application. ## Django routes the request to a view in urls.py files There are various [urls.py](https://docs.djangoproject.com/en/1.8/topics/http/urls/) files throughout the server codebase, which are -covered in more detail in [the directory structure doc](directory-structure.html). +covered in more detail in [the directory structure doc](../overview/directory-structure.html). The main Zulip Django app is `zerver`. The routes are found in ``` diff --git a/docs/new-feature-tutorial.md b/docs/tutorials/new-feature-tutorial.md similarity index 96% rename from docs/new-feature-tutorial.md rename to docs/tutorials/new-feature-tutorial.md index 61aeb9eab2..8f3a004fa1 100644 --- a/docs/new-feature-tutorial.md +++ b/docs/tutorials/new-feature-tutorial.md @@ -8,7 +8,7 @@ data system in real-time to all browsers the user may have open. As you read this, you may find you need to learn about Zulip's real-time push system; the -[real-time push and events](events-system.html) documentation has a +[real-time push and events](../subsystems/events-system.html) documentation has a detailed explanation of how everything works. ## General Process @@ -60,7 +60,7 @@ organization in Zulip). The following files are involved in the process: **Test your changes:** Once you've run the migration, flush memcached on your development server (`./scripts/setup/flush-memcached`) and then [restart the development server]( -http://zulip.readthedocs.io/en/latest/dev-remote.html?highlight=tools%2Frun-dev.py#running-the-development-server) +../development/remote.html?highlight=tools%2Frun-dev.py#running-the-development-server) to avoid interacting with cached objects. ### Backend changes @@ -110,7 +110,7 @@ precompiled as part of the build/deploy process. Zulip is fully internationalized, so when writing both HTML templates or JavaScript code that generates user-facing strings, be sure to -[tag those strings for translation](translating.html). +[tag those strings for translation](../translating/translating.html). **Testing:** There are two types of frontend tests: node-based unit tests and blackbox end-to-end tests. The blackbox tests are run in a @@ -118,14 +118,14 @@ headless browser using Casper.js and are located in `frontend_tests/casper_tests/`. The unit tests use Node's `assert` module are located in `frontend_tests/node_tests/`. For more information on writing and running tests, see the -[testing documentation](testing.html). +[testing documentation](../testing/testing.html). ### Documentation changes After implementing the new feature, you should document it and update any existing documentation that might be relevant to the new feature. For more information on the kinds of -documentation Zulip has, see [Documentation](documentation.html). +documentation Zulip has, see [Documentation](../subsystems/documentation.html). ## Example Feature @@ -227,7 +227,7 @@ Running migrations: Once you've run the migration, restart memcached on your development server (`/etc/init.d/memcached restart`) and then [restart the development server]( -http://zulip.readthedocs.io/en/latest/dev-remote.html?highlight=tools%2Frun-dev.py#running-the-development-server) +../development/remote.html?highlight=tools%2Frun-dev.py#running-the-development-server) to avoid interacting with cached objects. ### Handle database interactions @@ -246,7 +246,7 @@ initial state. Subsequently, clients subscribe to "events," which can For the backend piece, we will need our action to make a call to `send_event` to send the event to clients that are active. We will also need to modify `fetch_initial_state_data` so that the new field is passed to -clients. See [our event system docs](events-system.html) for all the +clients. See [our event system docs](../subsystems/events-system.html) for all the gory details. Anyway, getting back to implementation details... @@ -435,7 +435,7 @@ with the new value. E.g., for `authentication_methods`, we created # ... This completes the backend implementation. A great next step is to -write the [backend tests](testing-with-django.html). +write the [backend tests](../testing/testing-with-django.html). ### Backend Tests @@ -570,8 +570,8 @@ the associated function to update the application's UI, if necessary. ### Front End Tests A great next step is to write front end tests. There are two types of -frontend tests: [node-based unit tests](testing-with-node.html) and -[Casper end-to-end tests](testing-with-casper.html). +frontend tests: [node-based unit tests](../testing/testing-with-node.html) and +[Casper end-to-end tests](../testing/testing-with-casper.html). At the minimum, if you created a new function to update UI in `settings_org.js`, you will need to mock that function in @@ -604,7 +604,7 @@ At the very least, this will involve adding (or modifying) a Markdown file documenting the feature to `templates/zerver/help/` in the main Zulip server repository, where the source for Zulip's user documentation is stored. For information on writing user documentation, see -[Zulip's general user guide documentation](user-docs.html). +[Zulip's general user guide documentation](../subsystems/user-docs.html). For a more concrete example of writing documentation for a new feature, see [an example commit in the Zulip repo]( diff --git a/docs/reading-list.md b/docs/tutorials/reading-list.md similarity index 99% rename from docs/reading-list.md rename to docs/tutorials/reading-list.md index 0c047b6e85..d453ae5e6e 100644 --- a/docs/reading-list.md +++ b/docs/tutorials/reading-list.md @@ -148,7 +148,7 @@ Some titles have been shortened for organizational purposes. You may want to take a look first at our [Git and GitHub guide][]. -[Git and GitHub guide]: http://zulip.readthedocs.io/en/latest/git-guide.html +[Git and GitHub guide]: ../contributing/git-guide.html *Article* - [Git tips][] diff --git a/docs/screenshot-and-gif-software.md b/docs/tutorials/screenshot-and-gif-software.md similarity index 100% rename from docs/screenshot-and-gif-software.md rename to docs/tutorials/screenshot-and-gif-software.md diff --git a/docs/shell-tips.md b/docs/tutorials/shell-tips.md similarity index 98% rename from docs/shell-tips.md rename to docs/tutorials/shell-tips.md index e53001a73b..3379b592e9 100644 --- a/docs/shell-tips.md +++ b/docs/tutorials/shell-tips.md @@ -4,7 +4,7 @@ The *shell* is a **command line interpreter**. To use it you can open a *terminal* (sometimes called a *console*). This is how most terminal windows look like: -![An example shell window](images/shell-screenshot.png) +![An example shell window](../images/shell-screenshot.png) If you haven't used it before, you should probably take a look at [this tutorial](http://linuxcommand.org/lc3_learning_the_shell.php). @@ -339,7 +339,7 @@ At first it seems like magic, but once you get the basic concepts you find it extremely useful and even easy to use (at least the 99% of the time). To learn more about how to use it, read -[our docs](http://zulip.readthedocs.io/en/latest/git-guide.html) on Git and +[our docs](../contributing/git-guide.html) on Git and Github. [This cheatsheet][git-cheat-detailed] diff --git a/docs/webhook-walkthrough.md b/docs/tutorials/webhook-walkthrough.md similarity index 96% rename from docs/webhook-walkthrough.md rename to docs/tutorials/webhook-walkthrough.md index 8baeb63a4b..2ff4b9b4ae 100644 --- a/docs/webhook-walkthrough.md +++ b/docs/tutorials/webhook-walkthrough.md @@ -40,7 +40,7 @@ for each distinct message condition your webhook supports. You'll also need a corresponding fixture for each of these tests. Depending on the type of data the 3rd party service sends, your fixture may contain JSON, URL encoded text, or some other kind of data. See [Step 4: Create tests](#step-4-create-tests) or -[Testing](testing.html) for further details. +[Testing](../testing/testing.html) for further details. ## Step 1: Initialize your webhook python package @@ -124,7 +124,7 @@ it must exist before a message can be created in it. (See [Step 4: Create tests](#step-4-create-tests) for how to handle this in tests.) The line that begins `# type` is a mypy type annotation. See [this -page](mypy.html) for details about how to properly annotate your webhook +page](../contributing/mypy.html) for details about how to properly annotate your webhook functions. In the body of the function we define the body of the message as `Hello! I am @@ -204,7 +204,7 @@ After which you should see: Using either method will create a message in Zulip: -![Image of Hello World webhook message](images/helloworld-webhook.png) +![Image of Hello World webhook message](../images/helloworld-webhook.png) ## Step 4: Create tests @@ -332,7 +332,7 @@ The Hello World webhook will use the `test` stream, which is created by default in the Zulip dev environment. If you are running Zulip in production, you should make sure that this stream exists. -Next, on your {{ settings_html|safe }}, create a Hello World bot. +Next, on your {{ ../subsystems/settings.html|safe }}, create a Hello World bot. Construct the URL for the Hello World bot using the API key and stream name: @@ -373,11 +373,11 @@ available in the Zulip product, follow these steps to prepare your pull request: 1. Run tests including linters and ensure you have addressed any issues they - report. See [Testing](testing.html) and [Linters](linters.html) for details. -2. Read through [Code styles and conventions](code-style.html) and take a look + report. See [Testing](../testing/testing.html) and [Linters](../testing/linters.html) for details. +2. Read through [Code styles and conventions](../contributing/code-style.html) and take a look through your code to double-check that you've followed Zulip's guidelines. 3. Take a look at your git history to ensure your commits have been clear and - logical (see [Version Control](version-control.html) for tips). If not, + logical (see [Version Control](../contributing/version-control.html) for tips). If not, consider revising them with `git rebase --interactive`. For most webhooks, you'll want to squash your changes into a single commit and include a good, clear commit message. @@ -386,9 +386,9 @@ request: If you would like feedback on your integration as you go, feel free to post a message on the [public Zulip instance](https://chat.zulip.org/#narrow/stream/bots). -You can also create a [`[WIP]` pull request](contributing.html#working-on-an-issue) +You can also create a [`[WIP]` pull request](../overview/contributing.html#working-on-an-issue) while you are still working on your integration. See the -[Git guide](git-guide.html#create-a-pull-request) for more on Zulip's pull +[Git guide](../contributing/git-guide.html#create-a-pull-request) for more on Zulip's pull request process. ## Advanced topics diff --git a/docs/working-copies.md b/docs/tutorials/working-copies.md similarity index 100% rename from docs/working-copies.md rename to docs/tutorials/working-copies.md diff --git a/docs/writing-views.md b/docs/tutorials/writing-views.md similarity index 97% rename from docs/writing-views.md rename to docs/tutorials/writing-views.md index c817093bd2..2052f4ed94 100644 --- a/docs/writing-views.md +++ b/docs/tutorials/writing-views.md @@ -3,16 +3,16 @@ ## What this covers This page documents how views work in Zulip. You may want to read the -[new feature tutorial](new-feature-tutorial.html) -or the [integration guide](integration-guide.html), +[new feature tutorial](../tutorials/new-feature-tutorial.html) +or the [integration guide](../tutorials/integration-guide.html), and treat this as a reference. If you have experience with Django, much of this will be familiar, but you may want to read about how REST requests are dispatched, and how request authentication works. -This document supplements the [new feature tutorial](new-feature-tutorial.html) -and the [testing](testing.html) +This document supplements the [new feature tutorial](../tutorials/new-feature-tutorial.html) +and the [testing](../testing/testing.html) documentation. ## What is a view? @@ -367,4 +367,4 @@ def api_pagerduty_webhook(request, user_profile, ``` `request.client` will be the result of `get_client("ZulipPagerDutyWebhook")` in this example and it will be passed to `check_send_stream_message`. For -more information, see [Clients in Zulip](client.html). +more information, see [Clients in Zulip](../subsystems/client.html). diff --git a/frontend_tests/run-casper b/frontend_tests/run-casper index fc7cbcb757..50fd92c1a7 100755 --- a/frontend_tests/run-casper +++ b/frontend_tests/run-casper @@ -106,7 +106,7 @@ def run_tests(files: Iterable[str], external_host: str) -> None: Oops, the frontend tests failed. Tips for debugging: * Check the frontend test server logs at %s * Check the screenshots of failed tests at var/casper/casper-failure*.png - * Try remote debugging the test web browser as described in docs/testing-with-casper.md + * Try remote debugging the test web browser as described in docs/testing/testing-with-casper.md """ % (LOG_FILE,), file=sys.stderr) sys.exit(ret) diff --git a/static/js/markdown.js b/static/js/markdown.js index 9da7e84dfc..1680a189ea 100644 --- a/static/js/markdown.js +++ b/static/js/markdown.js @@ -1,5 +1,5 @@ // This contains zulip's frontend markdown implementation; see -// docs/markdown.md for docs on our Markdown syntax. The other +// docs/subsystems/markdown.md for docs on our Markdown syntax. The other // main piece in rendering markdown client-side is // static/third/marked/lib/marked.js, which we have significantly // modified from the original implementation. diff --git a/static/js/typing.js b/static/js/typing.js index 3a07a8e84d..5faec40370 100644 --- a/static/js/typing.js +++ b/static/js/typing.js @@ -5,7 +5,7 @@ var exports = {}; // We detect changes in the compose box and notify the server // when we are typing. For the inbound side see typing_events.js. // -// See docs/typing-indicators.md for details on typing indicators. +// See docs/subsystems/typing-indicators.md for details on typing indicators. function send_typing_notification_ajax(recipients, operation) { channel.post({ diff --git a/static/js/typing_data.js b/static/js/typing_data.js index ce1e784ed1..0adca25740 100644 --- a/static/js/typing_data.js +++ b/static/js/typing_data.js @@ -1,7 +1,7 @@ var typing_data = (function () { var exports = {}; -// See docs/typing-indicators.md for details on typing indicators. +// See docs/subsystems/typing-indicators.md for details on typing indicators. var typist_dct = new Dict(); var inbound_timer_dict = new Dict(); diff --git a/static/js/typing_events.js b/static/js/typing_events.js index 26ebcc9c7b..0138a61f6e 100644 --- a/static/js/typing_events.js +++ b/static/js/typing_events.js @@ -1,7 +1,7 @@ var typing_events = (function () { var exports = {}; -// See docs/typing-indicators.md for details on typing indicators. +// See docs/subsystems/typing-indicators.md for details on typing indicators. // This code handles the inbound side of typing notifications. // When another user is typing, we process the events here. diff --git a/static/js/typing_status.js b/static/js/typing_status.js index 39497999d5..30884614e7 100644 --- a/static/js/typing_status.js +++ b/static/js/typing_status.js @@ -2,7 +2,7 @@ var typing_status = (function () { var exports = {}; -// See docs/typing-indicators.md for details on typing indicators. +// See docs/subsystems/typing-indicators.md for details on typing indicators. // The following constants are tuned to work with // TYPING_STARTED_EXPIRY_PERIOD, which is what the other diff --git a/tools/documentation_crawler/documentation_crawler/spiders/common/spiders.py b/tools/documentation_crawler/documentation_crawler/spiders/common/spiders.py index 5deba12429..c8922c3a58 100644 --- a/tools/documentation_crawler/documentation_crawler/spiders/common/spiders.py +++ b/tools/documentation_crawler/documentation_crawler/spiders/common/spiders.py @@ -13,7 +13,7 @@ EXCLUDED_URLS = [ # Google calendar returns 404s on HEAD requests unconditionally 'https://calendar.google.com/calendar/embed?src=ktiduof4eoh47lmgcl2qunnc0o@group.calendar.google.com', # Returns 409 errors to HEAD requests frequently - 'https://medium.freecodecamp.com', + 'https://medium.freecodecamp.org/', # Returns 404 to HEAD requests unconditionally 'https://www.git-tower.com/blog/command-line-cheat-sheet/', ] diff --git a/tools/linter_lib/custom_check.py b/tools/linter_lib/custom_check.py index 04cd6902a9..dde06d6023 100644 --- a/tools/linter_lib/custom_check.py +++ b/tools/linter_lib/custom_check.py @@ -395,12 +395,12 @@ def build_custom_checkers(by_lang): 'zerver/migrations/0060_move_avatars_to_be_uid_based.py', 'zerver/migrations/0104_fix_unreads.py', ]), - 'description': "Don't import models or other code in migrations; see docs/schema-migrations.md", + 'description': "Don't import models or other code in migrations; see docs/subsystems/schema-migrations.md", }, {'pattern': 'datetime[.](now|utcnow)', 'include_only': set(["zerver/", "analytics/"]), 'description': "Don't use datetime in backend code.\n" - "See https://zulip.readthedocs.io/en/latest/code-style.html#naive-datetime-objects", + "See https://zulip.readthedocs.io/en/latest/contributing/code-style.html#naive-datetime-objects", }, {'pattern': 'render_to_response\(', 'description': "Use render() instead of render_to_response().", @@ -453,7 +453,7 @@ def build_custom_checkers(by_lang): 'description': "github should be spelled GitHub"}, {'pattern': '[oO]rganisation', # exclude usage in hrefs/divs 'description': "Organization is spelled with a z", - 'exclude_line': [('docs/french.md', '* organization - **organisation**')]}, + 'exclude_line': [('docs/translating/french.md', '* organization - **organisation**')]}, {'pattern': '!!! warning', 'description': "!!! warning is invalid; it's spelled '!!! warn'"}, {'pattern': 'Terms of service', @@ -477,7 +477,7 @@ def build_custom_checkers(by_lang): {'pattern': 'aria-label="[^{]', 'description': "`aria-label` value should be translatable."}, {'pattern': 'script src="http', - 'description': "Don't directly load dependencies from CDNs. See docs/front-end-build-process.md"}, + 'description': "Don't directly load dependencies from CDNs. See docs/subsystems/front-end-build-process.md"}, {'pattern': "title='[^{]", 'description': "`title` value should be translatable."}, {'pattern': 'title="[^{\:]', @@ -652,12 +652,12 @@ def build_custom_checkers(by_lang): markdown_docs_length_exclude = { "api/bots/converter/readme.md", "templates/zerver/api/running-bots.md", - "docs/dev-env-first-time-contributors.md", - "docs/webhook-walkthrough.md", - "docs/life-of-a-request.md", - "docs/logging.md", + "docs/development/setup-vagrant.md", + "docs/tutorials/webhook-walkthrough.md", + "docs/tutorials/life-of-a-request.md", + "docs/subsystems/logging.md", "docs/migration-renumbering.md", - "docs/readme-symlink.md", + "docs/overview/readme-symlink.md", "README.md", "zerver/webhooks/helloworld/doc.md", "zerver/webhooks/trello/doc.md", diff --git a/tools/setup/emoji/build_emoji b/tools/setup/emoji/build_emoji index 6bf3b5b91b..e9bc4edd81 100755 --- a/tools/setup/emoji/build_emoji +++ b/tools/setup/emoji/build_emoji @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # -# See docs/emoji.md for a high-level explanation of how this system +# See docs/subsystems/emoji.md for a high-level explanation of how this system # works. import os import sys diff --git a/tools/setup/emoji/emoji_setup_utils.py b/tools/setup/emoji/emoji_setup_utils.py index 615b969129..0ca2d1f3ef 100644 --- a/tools/setup/emoji/emoji_setup_utils.py +++ b/tools/setup/emoji/emoji_setup_utils.py @@ -4,7 +4,7 @@ # otherwise there will be a ton of duplicates alphabetically next to # each other, which is confusing and looks bad (e.g. `angry` and # `angry_face` or `ab` and `ab_button` will always sort next to each -# other, and you really want to just pick one). See docs/emoji.md for +# other, and you really want to just pick one). See docs/subsystems/emoji.md for # details on how this system works. from collections import defaultdict diff --git a/tools/test-documentation b/tools/test-documentation index 58b4c6627d..7d28b60567 100755 --- a/tools/test-documentation +++ b/tools/test-documentation @@ -13,9 +13,14 @@ case $1 in ;; esac -cd "$(dirname "$0")"/.. -./tools/build-docs -cd ./tools/documentation_crawler +cd "$(dirname "$0")"/../docs +rm -rf _build +# collapse_navigation is set to False in conf.py to improve sidebar navigation for users. +# However, we must change its value to True before we begin testing links. +# Otherwise, sphinx would generate a large number of links we don't need to test. +# The crawler would take a very long time to finish and TravisCI would fail as a result. +sphinx-build -b html -d _build/doctrees -D html_theme_options.collapse_navigation=True . _build/html +cd ../tools/documentation_crawler echo -en "\033[0;94m" echo "Testing links in documentation..." diff --git a/zerver/lib/bugdown/__init__.py b/zerver/lib/bugdown/__init__.py index c3bd9c4d06..92bd395867 100644 --- a/zerver/lib/bugdown/__init__.py +++ b/zerver/lib/bugdown/__init__.py @@ -1,4 +1,4 @@ -# Zulip's main markdown implementation. See docs/markdown.md for +# Zulip's main markdown implementation. See docs/subsystems/markdown.md for # detailed documentation on our markdown syntax. from typing import Any, Callable, Dict, Iterable, List, Optional, Set, Text, Tuple, TypeVar, Union from mypy_extensions import TypedDict