Zulip docs

Author: MarkBruns

docs/.gitignore

@@ -0,0 +1 @@
+/_build

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -j auto -W
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,6 @@
+# Zulip Markdown documentation hosted elsewhere
+
+The Markdown files in this directory ( /zulip/docs ) are not intended
+to be read on GitHub. Instead, visit our
+[ReadTheDocs](https://zulip.readthedocs.io/en/latest/index.html) to
+read the Zulip documentation.

docs/THIRDPARTY

@@ -0,0 +1,11 @@
+/* override table width restrictions */
+.wy-table-responsive table td,
+.wy-table-responsive table th {
+    /* !important prevents the common CSS stylesheets from
+       overriding this as on RTD they are loaded after this stylesheet */
+    white-space: normal !important;
+}
+
+.wy-table-responsive {
+    overflow: visible !important;
+}

docs/_static/theme_overrides.css

@@ -0,0 +1,27 @@
+{% extends "!layout.html" %}
+
+{% block document %}
+    {#
+    # This allows us to insert a warning that appears only on the development
+    # version e.g. to say that something is likely to have changed.
+    # For more info see: https://www.sphinx-doc.org/en/master/templating.html
+    #}
+    {% if pagename in [] and release.endswith('+git') %}
+    {#
+    # This page doesn't exist in the stable documentation yet.
+    # This temporary workaround prevents test failures and should be removed after the next release.
+    #}
+    <div class="admonition warning">
+        <p class="first admonition-title">Warning</p>
+        <p class="last">You are reading a <strong>development version</strong> of the Zulip documentation. These instructions may contain changes that are not yet present in a supported Zulip Server release.
+        See <a class="reference external" href="https://zulip.readthedocs.io/en/stable/production/">documentation for the latest stable release</a>.</p>
+    </div>
+    {% elif pagename.split("/")[0] == "production" and release.endswith('+git') %}
+    <div class="admonition warning">
+        <p class="first admonition-title">Warning</p>
+        <p class="last">You are reading a <strong>development version</strong> of the Zulip documentation. These instructions may contain changes that are not yet present in a supported Zulip Server release.
+        See <a class="reference external" href="https://zulip.readthedocs.io/en/stable/{{ pagename }}.html">documentation for the latest stable release</a>.</p>
+    </div>
+    {% endif %}
+    {{ super() }}
+{% endblock %}

docs/_templates/layout.html

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

docs/code-of-conduct.md

@@ -0,0 +1,57 @@
+# For documentation on Sphinx configuration options, see:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+# https://myst-parser.readthedocs.io/en/latest/sphinx/reference.html
+# https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html
+
+import os
+import sys
+from typing import Any
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+from version import LATEST_RELEASE_VERSION, ZULIP_VERSION
+
+on_rtd = os.environ.get("READTHEDOCS") == "True"
+
+# General configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx_rtd_theme",
+]
+templates_path = ["_templates"]
+project = "Zulip"
+copyright = "2012–2015 Dropbox, Inc., 2015–2021 Kandra Labs, Inc., and contributors"
+author = "The Zulip Team"
+version = ZULIP_VERSION
+release = ZULIP_VERSION
+exclude_patterns = ["_build", "README.md"]
+suppress_warnings = [
+    "myst.header",
+]
+pygments_style = "sphinx"
+
+# Options for Markdown parser
+
+myst_enable_extensions = [
+    "colon_fence",
+    "substitution",
+]
+myst_heading_anchors = 6
+myst_substitutions = {
+    "LATEST_RELEASE_VERSION": LATEST_RELEASE_VERSION,
+}
+
+# Options for HTML output
+
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "collapse_navigation": not on_rtd,  # makes local builds much faster
+    "logo_only": True,
+}
+html_logo = "images/zulip-logo.svg"
+html_static_path = ["_static"]
+
+
+def setup(app: Any) -> None:
+    # overrides for wide tables in RTD theme
+    app.add_css_file("theme_overrides.css")  # path relative to _static

docs/conf.py

@@ -0,0 +1,54 @@
+# Asking great questions
+
+A well-formed question helps you learn, respects the person answering, and makes
+efficient use of time for everyone involved. Asking the right question, to the
+right person, in the right way, at the right time, is a skill which requires a
+lifetime of fine-tuning. This page offers some guidelines and resources that the
+[Zulip community](https://zulip.com/development-community/) has found helpful in this pursuit.
+
+## Where to ask your question
+
+It is almost always best to ask questions and have a conversation in a public
+stream, rather than in direct messages. You’ll get better and faster answers
+since many people can help, and it makes it possible for others to benefit from
+the discussion.
+
+The [Zulip community
+guide](https://zulip.com/development-community/#where-do-i-send-my-message)
+offers guidelines on how the major public streams in the community are used.
+Don’t stress too much about picking the right place if you’re not sure, as
+moderators can [move your question thread to a different
+stream](https://zulip.com/help/move-content-to-another-stream) if needed.
+
+## How to ask a great question
+
+Spending some extra time and effort to carefully formulate your question is well
+worthwhile, as it makes it much more likely that you'll get the information you
+need to move forward. There are a few wonderfully thoughtful blog posts that
+explain what it means to ask a good question:
+
+- [Try, Then Ask](https://www.mattringel.com/2013/09/30/you-must-try-and-then-you-must-ask/)
+- [We Aren’t Just Making Code, We’re Making History](https://www.harihareswara.net/sumana/2016/10/12/0)
+- [How to Ask Good Questions](https://jvns.ca/blog/good-questions/)
+
+In brief, to formulate a great question, you should:
+
+- Try to solve your own problem first, including reading through relevant
+  documentation and code.
+- Identify the precise point on which you feel stuck.
+- Formulate a clear question, which includes an appropriate amount of context
+  and a specific request for help.
+
+When your question is answered, follow through on the advice you receive, and (when
+appropriate) summarize the resolution of your problem so that others can learn
+from your experience.
+
+You can find additional helpful tips in our guide to [what makes a great Zulip
+contributor](contributing.md#what-makes-a-great-zulip-contributor).
+
+## Follow the community guidelines
+
+As always, be sure to follow the [Zulip community
+norms](https://zulip.com/development-community/). In particular, check out [the
+section on getting help](https://zulip.com/development-community/#getting-help)
+before you post.