docs: Update docs about how to build the docs (#1970)

* docs: Update docs about how to build the docs

* Change name on sphinx targets

* Add doc-live-build

.markdownlintignore

@@ -1,4 +1,6 @@
 **/CHANGELOG.md
 **/ios/**
 **/doc/api/static-assets/**
-
+**/macos/**
+**/windows/**
+**/linux/**

doc/_sphinx/Makefile

@@ -13,6 +13,9 @@ help:
 
 .PHONY: help Makefile
 
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --open-browser
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

doc/_sphinx/requirements.txt

@@ -3,3 +3,4 @@ myst-parser>=0.15.2
 pygments>=2.10
 sphinx>=5.0
 sphinxcontrib-mermaid>=0.7.1
+sphinx-autobuild>=2021.3.14

doc/development/documentation.md

@@ -156,32 +156,37 @@ following:
       ```
 
 Once these prerequisites are met, you can build the documentation by switching to the `doc/_sphinx`
-directory and running `make html`:
+directory and running `make html`, or use the built-in Melos target:
 
 ```console
-cd doc/_sphinx
-make html
+melos doc-build
 ```
 
-The **make html** command here renders the documentation site into HTML. This command needs to be
-re-run every time you make changes to any of the documents. Luckily, it is smart enough to only
+The **melos doc-build** command here renders the documentation site into HTML. This command needs to
+be re-run every time you make changes to any of the documents. Luckily, it is smart enough to only
 rebuild the documents that have changed since the previous run, so usually a rebuild takes only
 a second or two.
 
-There are other make commands that you may find occasionally useful too: **make clean** removes all
-cached generated files (in case the system gets stuck in a bad state); and **make linkcheck** to
-check whether there are any broken links in the documentation.
+If you want to automatically recompile the docs every time there is a change to one of the files
+you can use the **melos doc-build-live** command, which will also serve and open your default
+browser with the docs.
+
+There are other make commands that you may find occasionally useful too:
+
+- **melos doc-clean** removes all cached generated files (in case the system gets stuck in a bad
+state).
+- **melos doc-linkcheck** to check whether there are any broken links in the documentation.
 
 The generated html files will be in the `doc/_build/html` directory, you can view them directly
 by opening the file `doc/_build/html/index.html` in your browser. The only drawback is that the
 browser won't allow any dynamic content in a file opened from a local drive. The solution to this
-is to run your own local http server:
+is to either run **melos doc-build-live** or run your own local http server:
 
 ```console
 python -m http.server 8000 --directory doc/_build/html
 ```
 
 Then you can open the site at `http://localhost:8000/`.
 
-If you ever run the `make clean` command, the server will need to be restarted, because the clean
-command deletes the entire `html` directory.
+If you ever run the **melos doc-clean** or the **make clean** command, the server will need to be
+restarted, because the clean command deletes the entire `html` directory.

melos.yaml

@@ -51,10 +51,22 @@ scripts:
     run: melos exec flutter pub run dartdoc
     description: Run dartdoc checks for all packages.
 
-  sphinxdoc:
+  doc-build:
     run: SOURCEDIR="$MELOS_ROOT_PATH/doc" && cd "$SOURCEDIR/_sphinx" && make html
     description: Create the sphinx html docs.
 
+  doc-build-live:
+    run: SOURCEDIR="$MELOS_ROOT_PATH/doc" && cd "$SOURCEDIR/_sphinx" && make livehtml
+    description: Recompiles the docs enerytime there is a change in them and opens your browser.
+
+  doc-clean:
+    run: SOURCEDIR="$MELOS_ROOT_PATH/doc" && cd "$SOURCEDIR/_sphinx" && make clean
+    description: Removes all Sphinx's cached generated files.
+
+  doc-linkcheck:
+    run: SOURCEDIR="$MELOS_ROOT_PATH/doc" && cd "$SOURCEDIR/_sphinx" && make linkcheck
+    description: Checks whether there are any broken links in the docs.
+
   test:select:
     run: melos exec -- flutter test
     select-package: