initial docs for CLI and config options

also includes improved scrollbar styling

Author: rmorshea

docs/source/_static/css/better-scrollbar.css

@@ -0,0 +1,51 @@
+Command-line
+============
+
+IDOM supplies a CLI for:
+
+- Displaying version information
+- Installing Javascript packages
+- Restoring IDOM's client
+
+
+Show Version Info
+-----------------
+
+To see the version of ``idom`` being run:
+
+.. code-block:: bash
+
+    idom version
+
+You can also show all available versioning information:
+
+.. code-block:: bash
+
+    idom version --verbose
+
+This is useful for bug reports.
+
+
+Install Javascript Packages
+---------------------------
+
+You can install Javascript packages at the command line rather than doing it
+:ref:`programmatically <Dynamically Install Javascript>`:
+
+.. code-block:: bash
+
+    idom install some-js-package versioned-js-package@^1.0.0
+
+If the package is already installed then the build will be skipped.
+
+
+Restore The Client
+------------------
+
+Replace IDOM's client with a backup from its original installation.
+
+.. code-block:: bash
+
+    idom restore
+
+This is useful if a build of the client fails and leaves it in an unusable state.

docs/source/command-line.rst

@@ -0,0 +1,12 @@
+Configuration Options
+=====================
+
+IDOM provides a series of configuration options that can be set using environment
+variables or, for those which allow it, using a programatic interface.
+
+.. automodule:: idom.config
+    :members:
+
+
+.. autoclass:: idom.config._option.Option
+    :members:

docs/source/configuration-options.rst

@@ -10,11 +10,18 @@ Libraries for defining and controlling interactive webpages with Python
     installation
     getting-started
     life-cycle-hooks
+    package-api
+    examples
+
+.. toctree::
+    :hidden:
+    :caption: Advanced Usage
+
     core-concepts
     javascript-components
+    command-line
+    configuration-options
     specifications
-    package-api
-    examples
 
 .. toctree::
     :hidden:

docs/source/index.rst

@@ -17,13 +17,14 @@ For more installation options see the :ref:`Extra Features` section.
 
 .. note::
 
-    To contribute to IDOM, refer to the :ref:`Developer Guide` instructions.
+    IDOM also supplies a :ref:`Flake8 Plugin` to help enforce the :ref:`Rules of Hooks`
 
 
 Extra Features
 --------------
 
-Optionally installable features of IDOM. To install them use the given "Name" from the table below
+Optionally installable features of IDOM. To include, them use the given "Name" from the
+table below:
 
 .. code-block:: bash
 
@@ -136,9 +137,8 @@ How It Works
 Once ``idom`` has been imported at your application's entrypoint, any following modules
 imported with a ``# dialect=html`` header comment get transpiled just before they're
 executed. This is accomplished by using Pyalect_ to hook a transpiler into Pythons
-import system. The :class:`~idom.dialect.HtmlDialectTranspiler` which implements
-Pyalect_'s :class:`~pyalect.dialect.Transpiler` interface using some tooling from
-htm.py_.
+import system. The :class:`~idom.dialect.HtmlDialectTranspiler` implements Pyalect_'s
+:class:`~pyalect.dialect.Transpiler` interface using some tooling from htm.py_.
 
 
 .. Links

docs/source/installation.rst

@@ -300,7 +300,7 @@ Rules of Hooks
 
 Hooks are just normal Python functions, but there's a bit of magic to them, and in order
 for that magic to work you've got to follow two rules. Thankfully we supply a
-`Flake8 Linter Plugin`_ to help enforce them.
+:ref:`Flake8 Plugin` to help enforce them.
 
 
 Only call outside flow controls

docs/source/life-cycle-hooks.rst

@@ -97,10 +97,3 @@ Useful Tools
 
 .. automodule:: idom.utils
     :members:
-
-
-Configuration Options
----------------------
-
-.. automodule:: idom.config
-    :members:

docs/source/package-api.rst

@@ -14,27 +14,38 @@ def __init__(
         self,
         name: str,
         default: _O,
-        immutable: bool = False,
+        mutable: bool = True,
         validator: Callable[[Any], _O] = lambda x: cast(_O, x),
     ) -> None:
         self.name = name
         self._default = default
-        self._immutable = immutable
+        self._mutable = mutable
         self._validator = validator
         self._value = validator(os.environ.get(name, default))
 
+    @property
+    def mutable(self) -> bool:
+        """Whether this option can be modified after being loaded"""
+        return self._mutable
+
     def get(self) -> _O:
+        """Get the current value of this option."""
         return self._value
 
     def set(self, new: _O) -> _O:
-        if self._immutable:
+        """Set the value of this configuration option
+
+        Raises a ``TypeError`` if this option is immutable.
+        """
+        if not self._mutable:
             raise TypeError(f"{self} cannot be modified after initial load")
         old = self._value
         self._value = self._validator(new)
         return old
 
     def reset(self) -> _O:
+        """Reset the value of this option to its default setting"""
         return self.set(self._default)
 
     def __repr__(self) -> str:
-        return f"Option(name={self.name!r}, value={self._value!r})"
+        return f"Option({self.name}={self._value!r})"

src/idom/_option.py

@@ -1,26 +1,34 @@
 from pathlib import Path
+from typing import cast
 
 from . import _option
 
 
 IDOM_DEBUG_MODE = _option.Option(
     "IDOM_DEBUG_MODE",
     default=False,
-    immutable=True,
+    mutable=False,
     validator=lambda x: bool(int(x)),
 )
-"""Turn on/off debug mode"""
+"""This immutable option turns on/off debug mode
+
+The string values ``1`` and ``0`` are mapped to ``True`` and ``False`` respectively.
+
+When debug is on, extra validation measures are applied that negatively impact
+performance but can be used to catch bugs. Additionally, the default log level for IDOM
+is set to ``DEBUG``.
+"""
 
 IDOM_CLIENT_BUILD_DIR = _option.Option(
     "IDOM_CLIENT_BUILD_DIR",
     default=Path(__file__).parent / "client" / "build",
     validator=Path,
 )
-"""The location IDOM will use for its client application"""
+"""The location IDOM will use to store its client application"""
 
 IDOM_CLIENT_WEB_MODULE_BASE_URL = _option.Option(
     "IDOM_CLIENT_WEB_MODULE_BASE_URL",
     default=".",
-    validator=lambda x: str(x).rstrip("/"),
+    validator=lambda x: cast(str, x[:-1] if x.endswith("/") else x),
 )
 """The base URL where all user-installed web modules reside"""

src/idom/config.py

@@ -8,7 +8,7 @@
 
 def test_option_repr():
     opt = Option("A_FAKE_OPTION", "some-value")
-    assert repr(opt) == "Option(name='A_FAKE_OPTION', value='some-value')"
+    assert repr(opt) == "Option(A_FAKE_OPTION='some-value')"
 
 
 @mock.patch.dict(os.environ, {"A_FAKE_OPTION": "value-from-environ"})
@@ -36,7 +36,8 @@ def test_option_validator():
 
 
 def test_immutable_option():
-    opt = Option("A_FAKE_OPTION", "default-value", immutable=True)
+    opt = Option("A_FAKE_OPTION", "default-value", mutable=False)
+    assert not opt.mutable
     with pytest.raises(TypeError, match="cannot be modified after initial load"):
         opt.set("a-new-value")