Merge pull request #1861 from freakboy3742/m1-docs

Update docs contribution guide to include M1 details.

changes/1861.misc.rst

@@ -0,0 +1 @@
+A workaround for linting docs on M1 machines was documented.

core/src/toga/style/applicator.py

@@ -31,10 +31,10 @@ def set_hidden(self, hidden):
             # grandchildren.
             #
             # parent hidden child hidden style child final hidden state
-            # ============= ================== ======================== 
+            # ============= ================== ========================
             # True          True               True
             # True          False              True
-            # False         True               True 
+            # False         True               True
             # False         False              False
             child.applicator.set_hidden(hidden or child.style._hidden)
 

docs/how-to/contribute-docs.rst

@@ -34,6 +34,13 @@ You'll also need to install the Enchant spell checking library.
 
       (venv) $ brew install enchant
 
+    If you're on an M1 machine, you'll also need to manually set the location
+    of the Enchant library:
+
+    .. code-block:: bash
+
+      (venv) $ export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.2.dylib
+
   .. group-tab:: Linux
 
     Enchant can be installed as a system package:
@@ -82,7 +89,7 @@ Once your development environment is set up, run:
 
     .. code-block:: powershell
 
-      C:\...>tox -e docs
+      (venv) C:\...>tox -e docs
 
 The output of the file should be in the ``docs/_build/html`` folder. If there
 are any markup problems, they'll raise an error.
@@ -111,7 +118,7 @@ documentation:
 
     .. code-block:: powershell
 
-      C:\...>tox -e docs-lint
+      (venv) C:\...>tox -e docs-lint
 
 This will validate the documentation does not contain:
 
@@ -123,6 +130,40 @@ If a valid spelling of a word is identified as misspelled, then add the word to
 the list in ``docs/spelling_wordlist``. This will add the word to the
 spellchecker's dictionary.
 
+If you get an error related to SSL certificate verification::
+
+    Exception occurred:
+      File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/ssl.py", line 1342, in do_handshake
+        self._sslobj.do_handshake()
+    ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1007)
+
+The root certificate on your machine is out of date. You can correct this by
+installing the Python package `certifi`, and using that package to provide your
+SSL root certificate:
+
+.. tabs::
+
+  .. group-tab:: macOS
+
+    .. code-block:: bash
+
+      (venv) $ python -m pip install certifi
+      (venv) $ export SSL_CERT_FILE=$(python -m certifi)
+
+  .. group-tab:: Linux
+
+    .. code-block:: bash
+
+      (venv) $ python -m pip install certifi
+      (venv) $ export SSL_CERT_FILE=$(python -m certifi)
+
+  .. group-tab:: Windows
+
+    .. code-block:: powershell
+
+      (venv) C:\...>python -m pip install certifi
+      (venv) C:\...>FOR /f "delims=" %i IN ('python -m certifi') DO SET SSL_CERT_FILE=%i
+
 Rebuilding all documentation
 ----------------------------
 
@@ -146,7 +187,7 @@ To force a rebuild for all of the documentation:
 
     .. code-block:: powershell
 
-      C:\...>tox -e docs-all
+      (venv) C:\...>tox -e docs-all
 
 The documentation should be fully rebuilt in the ``docs/_build/html`` folder.
 If there are any markup problems, they'll raise an error.

tox.ini

@@ -56,6 +56,16 @@ skip_install = True
 change_dir = docs
 deps =
     ./core[docs]
+passenv =
+    # On macOS M1, you need to manually set the location of the PyEnchant
+    # library:
+    #     export PYENCHANT_LIBRARY_PATH/opt/homebrew/lib/libenchant-2.2.dylib
+    PYENCHANT_LIBRARY_PATH
+    # It is sometimes necessary to override the default certificate store
+    # so that PyPI can be contacted with XMLRPC:
+    #     pip install certifi
+    #     export SSL_CERT_FILE=$(python -m certifi)
+    SSL_CERT_FILE
 commands =
     !lint-!all : python -m sphinx {[docs]sphinx_args} -b html . {[docs]build_dir}/html
     lint : python -m sphinx {[docs]sphinx_args_extra} -b linkcheck . {[docs]build_dir}/links