Repository: zulip/zulip

Issue:
Clean out articles not referenced in the developer documentation TOC
This is a plan for how to clean up the remaining files in our ReadTheDocs that aren't properly managedin the TOC.

We should probably just delete these:
* /home/tabbott/zulip/docs/brief-install-vagrant-dev.md

We should just add these to the TOC:
* /home/tabbott/zulip/docs/code-of-conduct.md: maybe move it to contributing/
* /home/tabbott/zulip/docs/migration-renumbering.md: Move to subsystems/
* /home/tabbott/zulip/docs/production/email.md: Just add to production TOC
* /home/tabbott/zulip/docs/production/ssl-certificates.md: Just add to production TOC
* /home/tabbott/zulip/docs/subsystems/conversion.md: Just add to subsystems TOC
* /home/tabbott/zulip/docs/subsystems/input-pills.md: Just add to subsystems TOC
* /home/tabbott/zulip/docs/subsystems/unread_messages.md: Just add to subsystems TOC
* /home/tabbott/zulip/docs/users.md: Move to subsystems and add to subsystems TOC

These we probably actually just don't want in the TOC, and should figure out how to exclude from this warning:
* /home/tabbott/zulip/docs/production/expensive-migrations.md: 
* /home/tabbott/zulip/docs/production/install-existing-server.md: 
* /home/tabbott/zulip/docs/production/multiple-organizations.md
* /home/tabbott/zulip/docs/password-strength.md: Should move under production/ for better structure too.
* /home/tabbott/zulip/docs/request-remote-dev.md: Move to development/request-remote.md first.  Make sure to update zulip-gci repo too.





Discussion:
Hello @zulip/server-development members, this issue was labeled with the **area: documentation (developer)** label, so you may want to check it out!
@zulipbot  claim
Hey @Balaji2198, I can jump in and help with the few remaining files if you don't mind. I helped with the recent docs migration so I am already familiar with the clean up that needs to be done here.

Just to summarize, I think this is all that we have left to do:

Move the following files and update broken links accordingly
* docs/password-strength.md   -> docs/production/password-strength.md

Exclude the following files from warnings saying document's not included in TOC
* docs/production/expensive-migrations.md
* docs/production/install-existing-server.md
* docs/production/multiple-organizations.md
* docs/production/password-strength.md
docs/development/request-remote.md
Let's skip moving `code-of-conduct` for now.  I think it's possible we might want to leave it (and possibly some some things currently in "overview" out to the top level, so they're extra visible.
(Also, I think I moved request-remote)
Okay, got it. So does that also mean you want `code-of-conduct.md` added to the TOC? Do you want it above or below "Overview" on the nav bar?
I'm not sure; I was sorta thinking this would go with exploding "overview" to all be top-level (or mostly be top-level), so wanted to procrasinate a bit on figuring that out.
Okay cool, yeah that would make sense. The red warning for code-of-conduct.md will remind us about it later :)

Getting rid of the warnings while having the files not show up in the TOC is not very well documented in sphinx though. So I went ahead and made a PR that should complete this cleanup.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -34,6 +34,8 @@
 extensions = []  # type: List[str]
 
 # Add any paths that contain templates here, relative to this directory.
+# For more info about changes in _templates/layout.html,
+# see https://github.com/zulip/zulip/pull/7463.
 templates_path = ['_templates']
 
 # The encoding of source files.
diff --git a/tools/linter_lib/custom_check.py b/tools/linter_lib/custom_check.py
--- a/tools/linter_lib/custom_check.py
+++ b/tools/linter_lib/custom_check.py
@@ -489,7 +489,8 @@ def build_custom_checkers(by_lang):
         {'pattern': "aria-label='[^{]",
          'description': "`aria-label` value should be translatable."},
         {'pattern': 'aria-label="[^{]',
-         'description': "`aria-label` value should be translatable."},
+         'description': "`aria-label` value should be translatable.",
+         'exclude': set(["docs/_templates/layout.html"])},
         {'pattern': 'script src="http',
          'description': "Don't directly load dependencies from CDNs.  See docs/subsystems/front-end-build-process.md"},
         {'pattern': "title='[^{]",


Test patch: