From 62d555115a9c3c57899d45aa36be854f85b64868 Mon Sep 17 00:00:00 2001 From: David Rosa Date: Mon, 25 Nov 2019 15:25:49 -0800 Subject: [PATCH] docs: Improve formatting of important notes. Improves formatting using reST and Sphinx admonition directives so that important notes stand out when viewed in ReadTheDocs. --- docs/git/troubleshooting.md | 13 ++++++++----- docs/production/upgrade-or-modify.md | 17 +++++++++-------- docs/testing/linters.md | 15 +++++++++------ docs/testing/manual-testing.md | 10 +++++++--- 4 files changed, 33 insertions(+), 22 deletions(-) diff --git a/docs/git/troubleshooting.md b/docs/git/troubleshooting.md index 9e74e78c05..8757c24b94 100644 --- a/docs/git/troubleshooting.md +++ b/docs/git/troubleshooting.md @@ -72,11 +72,14 @@ $ git reset --hard 13bea0e HEAD is now at 13bea0e test commit for docs. ``` -**Important:** `git reset --hard ` will discard all changes in your -working directory and index since the commit you're resetting to with -``. *This is the main way you can lose work in Git*. If you need to -keep any changes that are in your working directory or that you have committed, -use `git reset --merge ` instead. +```eval_rst +.. important:: + ``git reset --hard `` will discard all changes in your + working directory and index since the commit you're resetting to with + ````. *This is the main way you can lose work in Git*. If you need + to keep any changes that are in your working directory or that you have + committed, use ``git reset --merge `` instead. +``` You can also use the relative reflog `HEAD@{1}` instead of the commit hash, just keep in mind that this changes as you run git commands. diff --git a/docs/production/upgrade-or-modify.md b/docs/production/upgrade-or-modify.md index 2a0b6379c5..eeb1ec0813 100644 --- a/docs/production/upgrade-or-modify.md +++ b/docs/production/upgrade-or-modify.md @@ -147,7 +147,7 @@ the version corresponding to the `restart-server` path you call. .. warning:: If you have modified configuration files installed by Zulip (e.g. the nginx configuration), the Zulip upgrade process will - overwrite your configuration when it does the `puppet apply`. + overwrite your configuration when it does the ``puppet apply``. ``` You can test whether this will happen assuming no upstream changes to @@ -538,11 +538,14 @@ business. #### Disabling unattended upgrades -**Important**: We recommend that you -[disable Ubuntu's unattended-upgrades][disable-unattended-upgrades], -and instead install apt upgrades manually. With unattended upgrades -enabled, the moment a new Postgres release is published, your Zulip -server will have its postgres server upgraded (and thus restarted). +```eval_rst +.. important:: + We recommend that you `disable Ubuntu's unattended-upgrades + `_ + and instead install apt upgrades manually. With unattended upgrades + enabled, the moment a new Postgres release is published, your Zulip + server will have its postgres server upgraded (and thus restarted). +``` When one of the services Zulip depends on (postgres, memcached, redis, rabbitmq) is restarted, that services will disconnect everything using @@ -557,8 +560,6 @@ Instead, we recommend installing updates for these services manually, and then restarting the Zulip server with `/home/zulip/deployments/current/scripts/restart-server` afterwards. -[disable-unattended-upgrades]: https://linoxide.com/ubuntu-how-to/enable-disable-unattended-upgrades-ubuntu-16-04/ - ## Contributing patches Zulip contains thousands of changes submitted by volunteer diff --git a/docs/testing/linters.md b/docs/testing/linters.md index 818031f96f..f4569fb9aa 100644 --- a/docs/testing/linters.md +++ b/docs/testing/linters.md @@ -51,12 +51,15 @@ note are: Finally, you can rely on our Travis CI setup to run linters for you, but it is good practice to run lint checks locally. -**Important:** We provide a - [Git pre-commit hook](http://localhost:9991/docs/git/zulip-tools.html#set-up-git-repo-script) - that can automatically run `tools/lint` on just the files that - changed (in a few 100ms) whenever you make a commit. This can save - you a lot of time, by automatically detecting linter errors as you - make them. +```eval_rst +.. important:: + We provide a + `Git pre-commit hook <../git/zulip-tools.html#set-up-git-repo-script>`_ + that can automatically run ``tools/lint`` on just the files that + changed (in a few 100ms) whenever you make a commit. This can save + you a lot of time, by automatically detecting linter errors as you + make them. +``` **Note:** The linters only check files that git tracks. Remember to `git add` new files before running lint checks. diff --git a/docs/testing/manual-testing.md b/docs/testing/manual-testing.md index b1529dc92c..3586b78e06 100644 --- a/docs/testing/manual-testing.md +++ b/docs/testing/manual-testing.md @@ -155,9 +155,13 @@ be watching unread counts. Of course, you also want to see messages show up in the message pane. And, finally, you should make sure that no messages outside the narrow show up in Cordelia's view. -**Important**: Make sure that Cordelia is subscribed to Verona but not -subscribed to Denmark; if not, you should use different streams -for your testing. + +```eval_rst +.. important:: + Make sure that Cordelia is subscribed to Verona but not + subscribed to Denmark; if not, you should use different streams + for your testing. +``` When testing narrows, you want to have Hamlet send the same message several times in a row, while cycling Cordelia through various narrows.