docs: rewrite install instructions to be easier to understand.
authorwhitequark <whitequark@whitequark.org>
Wed, 1 Jul 2020 03:32:17 +0000 (03:32 +0000)
committerLuke Kenneth Casson Leighton <lkcl@lkcl.net>
Fri, 31 Dec 2021 14:24:02 +0000 (14:24 +0000)
docs/_static/custom.css
docs/conf.py
docs/install.rst
docs/requirements.txt

index 43d1abf99150c0b721db3ca1ea184b1713e979de..e568e23505f7ff7d06087408906cb77401e2680c 100644 (file)
@@ -3,3 +3,12 @@
 
 /* Many of our diagnostics are even longer */
 .rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre { white-space: pre-wrap; }
+
+/* Override what contentui does to body style */
+.wy-nav-content { max-width: 800px !important; }
+
+/* Make rubrics work like h3 */
+.rst-content p.rubric {
+  font-size: 125%;
+  font-family: Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;
+}
index be03e7bc62a87a5db862ace681949bbe1e74cacc..c311e9c780b01ce1579dd90e318f573c2f37a129 100644 (file)
@@ -12,6 +12,7 @@ extensions = [
        "sphinx.ext.intersphinx",
        "sphinx.ext.doctest",
     "sphinx.ext.todo",
+    "sphinxcontrib.contentui",
     "sphinx_rtd_theme",
 ]
 
index d883e454ecc5b999c85d9591e56e1c85ac91a615..268bbd2acfd308334f8cb138013af8fd1729c866 100644 (file)
@@ -6,77 +6,79 @@ System requirements
 
 nMigen requires Python 3.6; it works on CPython_ 3.6 (or newer), and works faster on PyPy3.6_ 7.2 (or newer).
 
-Simulating nMigen code requires no additional software. However, a waveform viewer like GTKWave_ is invaluable for debugging.
+For most workflows, nMigen requires Yosys_ 0.9 (or newer). A compatible version of Yosys is distributed via PyPI_ for most popular platforms.
 
-Converting nMigen code to Verilog requires Yosys_ 0.9 (or newer).
+Simulating nMigen code requires no additional software. However, a waveform viewer like GTKWave_ is invaluable for debugging.
 
-Synthesizing, placing and routing an nMigen design for an FPGA requires Yosys_ 0.9 (or newer), as well as the FPGA family specific toolchain.
+Synthesizing, placing and routing an nMigen design for an FPGA requires the FPGA family specific toolchain.
 
 .. TODO: Link to FPGA family docs here
 
 .. _CPython: https://www.python.org/
 .. _PyPy3.6: https://www.pypy.org/
 .. _Yosys: http://www.clifford.at/yosys/
+.. _PyPI: https://pypi.org/
 .. _GTKWave: http://gtkwave.sourceforge.net/
 
 
+.. _install-deps:
+
 Installing prerequisites
 ========================
 
-... on Windows
---------------
-
-.. todo::
+.. content-tabs::
 
-   Determine what's appropriate here (do we put Python in PATH? what about Yosys? is there something better than GTKWave? do we just give up and suggest WSL?)
+   .. tab-container:: windows
+      :title: Windows
 
+      `Install Python <python:using-on-windows>`_, either from Windows Store or using the full installer. If using the full installer, make sure to install a 64-bit version of Python.
 
-... on Debian Linux
--------------------
+      .. todo::
 
-nMigen works on Debian 10 or newer. The required version of Yosys is available in the main repository since Debian 11, but requires the Backports_ repository on Debian 10. Run:
+         What about GTKWave?
 
-.. note: debian 10 provides: python3 3.7.3, yosys 0.8 (yosys 0.9 in backports)
-.. note: debian 11 provides: python3 3.8.2, yosys 0.9
+   .. tab-container:: macos
+      :title: macOS
 
-.. code-block:: shell
+      Install Homebrew_. Then, install Python and GTKWave by running:
 
-   $ sudo apt-get install python3-pip yosys gtkwave
+      .. code-block:: console
 
-.. _Backports: https://wiki.debian.org/Backports
+         $ brew install python gtkwave
 
+      .. _Homebrew: https://brew.sh
 
-... on Ubuntu Linux
--------------------
+   .. tab-container:: linux
+      :title: Linux
 
-nMigen works on Ubuntu 20.04 LTS or newer.
+      .. rubric:: Debian-based distributions
 
-.. note: ubuntu 20.04 provides: python3 3.8.2, yosys 0.9
+      Install Python and GTKWave by running:
 
-.. code-block:: shell
+      .. code-block:: console
 
-   $ sudo apt-get install python3-pip yosys gtkwave
+         $ sudo apt-get install python3-pip gtkwave
 
+      On architectures other than x86_64 and AArch64, install Yosys by running:
 
-... on macOS
-------------
+      .. code-block:: console
 
-nMigen works best with Homebrew_. Run:
+         $ sudo apt-get install yosys
 
-.. code-block:: shell
+      If Yosys 0.9 (or newer) is not available, `build Yosys from source`_.
 
-   $ brew install python yosys gtkwave
+      .. rubric:: Other distributions
 
-.. _Homebrew: https://brew.sh
+      Install Python and GTKWave from the package repository of your distribution.
 
+      On architectures other than x86_64 and AArch64, install Yosys from the package repository of your distribution.
 
-... on other platforms
-----------------------
+      If Yosys 0.9 (or newer) is not available, `build Yosys from source`_.
 
-Refer to the `Yosys README`_ for detailed build instructions.
+      .. _build Yosys from source: https://github.com/YosysHQ/yosys/#setup
 
-.. _Yosys README: https://github.com/YosysHQ/yosys/#setup
 
+.. _install:
 
 Installing nMigen
 =================
@@ -84,36 +86,124 @@ Installing nMigen
 The latest release of nMigen should work well for most applications. A development snapshot---any commit from the ``master`` branch of nMigen---should be similarly reliable, but is likely to include experimental API changes that will be in flux until the next release. With that in mind, development snapshots can be used to try out new functionality or to avoid bugs fixed since the last release.
 
 
+.. _install-release:
+
 Latest release
 --------------
 
-To install the latest release of nMigen, run:
+.. |release:install| replace:: To install the latest release of nMigen, run:
+
+.. content-tabs::
+
+   .. tab-container:: windows
+      :title: Windows
+
+      |release:install|
+
+      .. code-block:: doscon
+
+         > pip install --upgrade nmigen[builtin-yosys]
+
+   .. tab-container:: macos
+      :title: macOS
+
+      |release:install|
+
+      .. code-block:: console
+
+         $ pip install --upgrade nmigen[builtin-yosys]
+
+   .. tab-container:: linux
+      :title: Linux
+
+      If you **did not** install Yosys manually in the :ref:`previous step <install-deps>`, to install the latest release of nMigen, run:
+
+      .. code-block:: console
+
+         $ pip3 install --upgrade nmigen[builtin-yosys]
+
+      If you **did** install Yosys manually in the previous step, run:
 
-.. code-block:: shell
+      .. code-block:: console
 
-   $ pip3 install --upgrade nmigen
+         $ pip3 install --upgrade nmigen
 
 
+.. _install-develop:
+
 Development snapshot
 --------------------
 
-To install a development snapshot of nMigen for the first time, run:
+.. |snapshot:first-time| replace:: To install a development snapshot of nMigen for the first time, run:
+.. |snapshot:update| replace:: Any changes made to the ``nmigen`` directory will immediately affect any code that uses nMigen. To update the snapshot, run:
+.. |snapshot:reinstall| replace:: It is important to run the ``pip3 install --editable .[builtin-yosys]`` each time the development snapshot is updated in case package dependencies have been added or changed. Otherwise, code using nMigen may misbehave or crash with an ``ImportError``.
+
+.. content-tabs::
+
+   .. tab-container:: windows
+      :title: Windows
+
+      |snapshot:first-time|
+
+      .. code-block:: doscon
+
+         > git clone https://gitlab.com/nmigen/nmigen
+         > cd nmigen
+         > pip install --editable .[builtin-yosys]
+
+      |snapshot:update|
+
+      .. code-block:: doscon
+
+         > cd nmigen
+         > git pull --ff-only origin master
+         > pip install --editable .[builtin-yosys]
+
+      |snapshot:reinstall|
+
+   .. tab-container:: macos
+      :title: macOS
+
+      |snapshot:first-time|
+
+      .. code-block:: console
+
+         $ git clone https://gitlab.com/nmigen/nmigen
+         $ cd nmigen
+         $ pip install --editable .[builtin-yosys]
+
+      |snapshot:update|
+
+      .. code-block:: console
+
+         $ cd nmigen
+         $ git pull --ff-only origin master
+         $ pip install --editable .[builtin-yosys]
+
+      |snapshot:reinstall|
+
+   .. tab-container:: linux
+      :title: Linux
+
+      If you have :ref:`previously <install-deps>` installed Yosys manually, omit ``[builtin-yosys]`` from the following commands.
+
+      |snapshot:first-time|
 
-.. code-block:: shell
+      .. code-block:: console
 
-   $ git clone https://gitlab.com/nmigen/nmigen
-   $ cd nmigen
-   $ pip3 install --editable .
+         $ git clone https://gitlab.com/nmigen/nmigen
+         $ cd nmigen
+         $ pip3 install --editable .[builtin-yosys]
 
-Any changes made to the ``nmigen`` directory will immediately affect any code that uses nMigen. To update the snapshot, run:
+      |snapshot:update|
 
-.. code-block:: shell
+      .. code-block:: console
 
-   $ cd nmigen
-   $ git pull --ff-only origin master
-   $ pip3 install --editable .
+         $ cd nmigen
+         $ git pull --ff-only origin master
+         $ pip3 install --editable .[builtin-yosys]
 
-It is important to run the ``pip3 install --editable .`` each time the development snapshot is updated in case package dependencies have been added or changed.
+      |snapshot:reinstall|
 
 
 Installing board definitions
index 49e26f134ff15daec285fc1f9dda18297d7c93da..660f04aaaab18d1683aef72d8ce532d1e0d05a91 100644 (file)
@@ -1,3 +1,4 @@
 sphinx~=3.0
-sphinx-rtd-theme~=0.5.0
+sphinxcontrib-contentui~=0.2.5
 -e git+http://github.com/pygments/pygments.git#egg=pygments
+sphinx-rtd-theme~=0.5.0