This uses the myst_heading_anchors option to automatically generate
header anchors and make Sphinx aware of them. See
https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors.
Note: to be compatible with GitHub, MyST-Parser uses a slightly
different convention for .md fragment links than .html fragment links
when punctuation is involved. This does not affect the generated
fragment links in the HTML output.
Fixes#13264.
Signed-off-by: Anders Kaseorg <anders@zulip.com>
We previously had a convention of redundantly including the directory
in relative links to reduce mistakes when moving content from one file
to another. However, these days we have a broken link checker in
test-documentation, and after #21237, MyST-Parser will check relative
links (including fragments) when you run build-docs.
Signed-off-by: Anders Kaseorg <anders@zulip.com>
Recommonmark is no longer maintained, and MyST-Parser is much more
complete.
https://myst-parser.readthedocs.io/
Signed-off-by: Anders Kaseorg <anders@zulip.com>
* Moves "Management commands" to a top-level section.
* Moves "Scalability" as a subsection at the bottom of "Requirements".
* Moves "Monitoring" as a subsections at the bottom of "Troubleshooting".
* Replaces "API and your Zulip URL" with a link to REST API docs. This
documentation text has been irrelevant for some time.
* Removes maintain-secure-upgrade from the TOC but the file remains to
avoid breaking old links from release blog posts and emails.
Merges the "Upgrades" section from production/maintain-secure-upgrade.md
with production/modifying-zulip.md.
Contains significant textual changes by tabbott to read more clearly.
- Merges the "Backups" section from production/maintain-secure-upgrade.md
with existing "Backups" section in production/export-and-import.md.
- Cleans up and makes content more clear/explicit.
- Adds short missing section on how to use wal-e configuration.
- Removes a lot of previously duplicate text explaining the difference between
the tools.
- Various textual tweaks by tabbott.
Fixes#13184 and resolves#293.
- Updated 260+ links from ".html" to ".md" to reduce the number of issues
reported about hyperlinks not working when viewing docs on Github.
- Removed temporary workaround that suppressed all warnings reported
by sphinx build for every link ending in ".html".
Details:
The recent upgrade to recommonmark==0.5.0 supports auto-converting
".md" links to ".html" so that the resulting HTML output is correct.
Notice that links pointing to a heading i.e. "../filename.html#heading",
were not updated because recommonmark does not auto-convert them.
These links do not generate build warnings and do not cause any issues.
However, there are about ~100 such links that might still get misreported
as broken links. This will be a follow-up issue.
Background:
docs: pip upgrade recommonmark and CommonMark #13013
docs: Allow .md links between doc pages #11719Fixes#11087.
We have lots of documentation for Zulip developers; but previously
didn't have a nice top-level page for Zulip server administrators to
learn how to manage patches to Zulip.
We need to disable "CREATE EXTENSION pgroonga" in zulip-puppet-apply
by creating /usr/share/postgresql/10/pgroonga_setup.sql.applied.
Because PostgreSQL 10 isn't running in this case. If PostgreSQL 10
isn't running, we can't run "CREATE EXTENSION pgroonga".
We can't use pg_upgrade with PGroonga. PGroonga's install SQL
https://github.com/pgroonga/pgroonga/blob/master/data/pgroonga.sql has
conditions to support multiple PostgreSQL versions. So it's not safe
to use pg_upgrade. pg_upgrade copies metadata for PostgreSQL 9.5 to
PostgreSQL 10. We need to use pg_dump and pg_restore to upgrade
PGroonga correctly for PostgreSQL 10.
It's not required on Ubuntu Xenial (having been replaced by systemd)
and causes problems when installing/upgrading other packages; this
change matches a similar block of code in our installer.
The comment explains this in more detail, but basically one previously
needed the `--from-git` option to `upgrade-zulip-stage-2` if one had
last installed/upgraded from Git, and not that option otherwise, which
would have forced us to make the OS upgrade documentation much more
complicated than it needed to be.
One longstanding gap in our production documentation is how to
properly do an upgrade to the operating system on which Zulip is
installed.
This adds that documentation.
Ideally, we'd get a few folks to test this procedure over the next few
days to make sure it's bulletproof.
Fixes#1705.
Fixes#10796.
Sphinx/ReadTheDocs supports automatically translating links written as
to `.md` files to point to the corresponding `.html` files, so this
migration does not change the resulting HTML output in ReadTheDocs.
But it does fix apparent broken links on GitHub.
This doesn't prevent people from reading the documentation on GitHub
(so doesn't mitigate the fact that some rtd-specific syntax does not
render properly on GH), but it will prevent us from getting erroneous
issues reported about the hyperlinks not working.
Fixes: #11087.
Now that we have nice documentation for our export/import tools, we've
been seeing a lot of users trying to use that as their primary backup
process. Let's correct this.
I don't think this is exactly the right place to document this, but
I'm not sure there's a better one without some restructuring this page
in general (which would probably have value).
Fixes#8769.
The careful testing with dozens of realms was a discrete thing
that happened, not a general state that the tool was in;
certainly not the last state it was known to be in, as the rest
of the sentence explains how it hasn't been so carefully tested
since then. So "as of" doesn't fit.
This commit helps reduce clutter on the navigation sidebar.
Creates new directories and moves relevant files into them.
Modifies index.rst, symlinks, and image paths accordingly.
This commit also enables expandable/collapsible navigation items,
renames files in docs/development and docs/production,
modifies /tools/test-documentation so that it overrides a theme setting,
Also updates links to other docs, file paths in the codebase that point
to developer documents, and files that should be excluded from lint tests.
Note that this commit does not update direct links to
zulip.readthedocs.io in the codebase; those will be resolved in an
upcoming follow-up commit (it'll be easier to verify all the links
once this is merged and ReadTheDocs is updated).
Fixes#5265.
Anders Kaseorg
Tim Abbott
David Rosa
Tim Abbott
Mateusz Mandera
Anders Kaseorg
Kouhei Sutou
Shubham Padia
Mohit Maroliya
Samuel Searles-Bryant
Anders Kaseorg
Joshua Pan
Greg Price