- 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.
Add a specific command to restart Vagrant to adopt the new
configuration.
(When naïvely using only `vagrant halt` + `vagrant up --provision`,
external devices remained unable to connect; per `netstat -nltp`, the
host IP of forwarded ports remained `127.0.0.1`.)
This plugin automatically updates the VirtualBox Guest Additions in
the guest, which makes shared folders work more reliably.
Signed-off-by: Anders Kaseorg <anders@zulipchat.com>
Many Linux distros like Debian Buster, Fedora 29, etc. have a policy
where any services installed are disabled by default. So we should let
the developer know that they should explicitly enable and start the
Docker daemon.
Also, we should be verbose on how to do vagrant up using Docker as a
provider specifically (and similar for Virtualbox).
This also means the default dev environment is now based on Ubuntu
18.04 (bionic), part of our overall effort to migrate off Ubuntu
Trusty.
Signed-off-by: Anders Kaseorg <anders@zulipchat.com>
Two variables were declared and assigned the respective values of the
default settings for the system. If the keyword is used in the
~/.zulip-vagrant-config file, the value is assigned to the variable.
There is no straightforward way to customize the virtual machine's
number of cpus or memory, this commit addresses that fact.
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.
Add the recommendation in docs for not using GitHub Desktop client for
zulip code as it has a bug of keeping the symlinks disabled and ignoring
any configuration done to re-enable it resulting into failure to identify
the received symlinks leading to failing test cases in the zulip development
environment.
The history of this was that there was a period where half of Vagrant
releases were broken (for everyone, e.g. downloading a base container
didn't work). It seems Vagrant has cleaned up their act at this point.
We really just want 2.0.x, not a specific version, and the direct
links we had are now quite old.
Thanks to Jonathon Hinchley for reporting this.
Fixes#11836.
help.github.com seems to have a bug where HEAD on a redirected page
returns 404. This causes tools/test-documentation to fail. Fix it by
skipping the redirects.
Signed-off-by: Anders Kaseorg <andersk@mit.edu>
Older versions of virtual box were giving installation error in new
MacOS Mojave. While originally we considered changing the docs to
point to the current version 5.2.20, it seems better to just not pin a
version.
Significantly tweaked by tabbott.
On OSX, the user id and group id don't match. So while the previous
code was always wrong, it produced incorrect output there. We can fix
this by replacing `whoami` with `id -g` for finding the current user's
group ID.
This didn't really make much sense - it presented a quickstart summary
of the instructions as an item in the list of differences from the
Ubuntu case, plus that quickstart only incorporated one of the two
actual differences so it didn't work anyway. Given the networking
stuff, an actual quickstart isn't in the cards, so just cut that.
Also fix some small things while we're here.
Update version of Vagrant from 1.8.6 to 2.0.2.
Update version of VirtualBox from 5.1.8 to 5.2.6.
We needed to update Vagrant because older versions have networking
problems on modern Macs, resulting in weird `apt` errors when
provisioning.
Commit message and some text tweaked by tabbott.
This updates the developer documentation to recommend `git clone -c`
to set the git pull mode to be rebase by default in the repository
configuration.
The hope is that this will help minimize how often new contributors
end up accidentally messing up their PRs by using `git pull`.
Tweaked by tabbott to fix broken links and optimize the language.
Fixes: #7022.
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.
