merge: rewrite-docs

I've omitted docs/*.org from this merge, as there is still work left to
do there, but I am pushing the module docs early so folks can benefit
from the new docs sooner.

modules/lang/scala/README.org

@@ -1,57 +1,84 @@
-#+TITLE:   lang/scala
-#+DATE:    October 14, 2020
-#+SINCE:   v1.3
-#+STARTUP: inlineimages
+# -*- mode: doom-docs-org -*-
+#+title:    :lang scala
+#+subtitle: Java, but good
+#+created:  May 12, 2016
+#+since:    1.0
 
-* Table of Contents :TOC_3:noexport:
-- [[#description][Description]]
-  - [[#module-flags][Module Flags]]
-- [[#lsp-integration][=+lsp= Integration]]
-  - [[#prerequisites][Prerequisites]]
-    - [[#coursier][Coursier]]
-    - [[#metals][Metals]]
-  - [[#features][Features]]
-  - [[#notes][Notes]]
-
-* Description
+* Description :unfold:
 This module adds [[https://www.scala-lang.org][scala]] and [[https://www.scala-sbt.org/][sbt]] support to Doom Emacs.
 
-** Module Flags
-+ =+lsp= Enables integration for the metals LSP server.
+Through the power of [[https://scalameta.org/metals/docs/editors/overview.html][Metals]] (LSP) this module offers:
+- Goto Definition
+- Completions
+- Hover
+- Paremeter Hints
+- Find References
+- Run/Debug
+- Find Implementations
+- Rename Symbol
+- Code Actions
+- Document Symbols
+- Formatting
+- Folding
+- Organize Imports
 
+** Maintainers
+/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
 
-* =+lsp= Integration
+** Module flags
+- +lsp ::
+  Enable LSP support for ~scala-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
+  (supports metals).
+- +tree-sitter ::
+  Leverages tree-sitter for better syntax highlighting and structural text
+  editing. Requires [[doom-module:][:tools tree-sitter]].
 
-** Prerequisites
+** Packages
+- [[doom-package:][sbt-mode]]
+- [[doom-package:][scala-mode]]
+- [[doom-package:][lsp-metals]] if [[doom-module:][+lsp]]
+
+** Hacks
+/No hacks documented for this module./
+
+** TODO Changelog
+# This section will be machine generated. Don't edit it by hand.
+/This module does not have a changelog yet./
+
+* Installation
+[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
+
+** =+lsp= Integration
+To set up LSP support for Scala you'll need the Metals LSP server. To install it
+you need Coursier installed first:
 
 *** Coursier
-Note: Coursier is only required to install Metals. If system is running arch
-linux this step can be safely skipped.
+Coursier is only required to install Metals. If you're on Arch linux this step
+can be skipped.
 
 **** Ubuntu / Debian / Fedora
-#+BEGIN_SRC sh
+#+begin_src sh
 curl -fLo cs https://git.io/coursier-cli-linux &&
     chmod +x cs &&
     ./cs
-#+END_SRC
+#+end_src
 
 **** MacOS
-#+BEGIN_SRC sh
+#+begin_src sh
 curl -fLo cs https://git.io/coursier-cli-macos &&
     chmod +x cs &&
     (xattr -d com.apple.quarantine cs || true) &&
     ./cs
-#+END_SRC
+#+end_src
 
-**** Arch
-#+BEGIN_SRC sh
+**** Arch Linux
+#+begin_src sh
 yay -S coursier
-#+END_SRC
+#+end_src
 
 *** Metals
-
 **** Ubuntu / Debian / Fedora / MacOS
-Note: Update following command to latest version of metals [[https://scalameta.org/metals/docs/editors/emacs.html][found here]].
+Update following command to latest version of metals [[https://scalameta.org/metals/docs/editors/emacs.html][found here]].
 
 #+begin_src sh
 coursier bootstrap \
@@ -64,31 +91,34 @@ coursier bootstrap \
   -o /usr/local/bin/metals-emacs -f
 #+end_src
 
-**** Arch
-#+BEGIN_SRC sh
+**** Arch Linux
+#+begin_src sh
 yay -S metals
-#+END_SRC
+#+end_src
 
-** Features
-According to [[https://scalameta.org/metals/docs/editors/overview.html]] it adds
+* TODO Usage
+#+begin_quote
+ 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
+#+end_quote
 
-+ Goto Definition
-+ Completions
-+ Hover
-+ Paremeter Hints
-+ Find References
-+ Run/Debug
-+ Find Implementations
-+ Rename Symbol
-+ Code Actions
-+ Document Symbols
-+ Formatting
-+ Folding
-+ Organize Imports
+* TODO Configuration
+#+begin_quote
+ 🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
+#+end_quote
 
-** Notes
+* Troubleshooting
+[[doom-report:][Report an issue?]]
 
-+ Projects are required to have scala version =2.11.12=, =2.12.8=, =2.13.0= or greater.
-+ Latest version of sbt is recommended.
-+ Running =M-x lsp-metals-doctor-run= helps diagnose problems.
-+ Full reference here: https://scalameta.org/metals/docs/editors/emacs.html
+- Projects are required to have scala version =2.11.12=, =2.12.8=, =2.13.0= or
+  greater.
+- Latest version of sbt is recommended.
+- Running ~M-x lsp-metals-doctor-run~ helps diagnose problems.
+- Full reference here: https://scalameta.org/metals/docs/editors/emacs.html
+
+* Frequently asked questions
+/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
+
+* TODO Appendix
+#+begin_quote
+ 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
+#+end_quote