[Sphinx documentation] Extend section about FINN docker container modes

docs/finn/_build/html/_sources/getting_started.rst.txt

@@ -17,3 +17,39 @@ Requirements
 Running FINN in Docker
 ======================
 We use Docker extensively for developing and deploying FINN. If you are not familiar with Docker, there are many excellent `online resources <https://docker-curriculum.com/>`_ to get started. There is a Dockerfile in the root of the repository, as well as a `run-docker.sh` script that can be launched in the following modes:
+
+Getting an interactive shell for development or experimentation
+***************************************************************
+::
+  sh run_docker.sh
+   
+Simply running sh run-docker.sh without any additional arguments will clone the dependency repos, create a Docker container and give you a terminal with you can use for development for experimentation.
+
+.. warning:: the Docker container is spawned with the `--rm` option, so make sure that any important files you created inside the container are either in the /workspace/finn folder (which is mounted from the host computer) or otherwise backed up.
+
+.. note:: **Develop from host, run inside container:** The FINN repository directory will be mounted from the host, so that you can use a text editor on your host computer to develop and the changes will be reflected directly inside the container.
+
+Running the Jupyter notebooks
+*****************************
+::
+  sh run-docker.sh notebook
+
+This will launch the Jupyter notebook server inside a Docker container, and print a link on the terminal that you can open in your browser to run the FINN notebooks or create new ones. 
+.. note:: The link will look something like this (the token you get will be different):
+          http://127.0.0.1:8888/?token=f5c6bd32ae93ec103a88152214baedff4ce1850d81065bfc
+
+The run-docker.sh script forwards ports 8888 for Jupyter and 8081 for Netron, and launches the notebook server with appropriate arguments.
+
+Running the test suite directly
+*******************************
+::
+  sh run-docker.sh test
+
+FINN comes with a set of tests which can be launched using the command above. Note that some of the tests involve extra compilation and the entire test suite may take some time to complete.  
+
+Running the test suite using Jenkins
+************************************
+::
+  sh run-docker.sh jenkins
+       
+

docs/finn/_build/html/_sources/index.rst.txt

@@ -17,7 +17,7 @@ What is FINN?
 * The FINN project, which is an experimental framework from Xilinx Research Labs to explore deep neural network inference on FPGAs. It specifically targets quantized neural networks, with emphasis on generating dataflow-style architectures customized for each network. It includes tools for training quantized neural networks such as Brevitas, the FINN compiler, and the finn-hlslib Vivado HLS library of FPGA components for QNNs. An overview of the project can be taken from the following graphic and details can be seen on the `FINN project homepage <https://xilinx.github.io/finn/>`_.
 
 .. image:: ../img/finn-stack.png
-   :scale: 50%
+   :scale: 40%
    :align: center
 
 * The repository, this Read the Docs website corresponds to. It is about the FINN compiler, which is the centerpiece of the FINN project. The GitHub repository can be viewed using the link in the upper right corner. To learn more about the FINN compiler, use this website and for a hands-on experience the repository contains some Jupyter notebooks which can be found under this `link <https://github.com/Xilinx/finn/tree/dev/notebooks>`_.

docs/finn/_build/html/getting_started.html

@@ -85,7 +85,13 @@
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Getting Started</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#how-to-use-the-finn-compiler">How to use the FINN compiler</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#requirements">Requirements</a></li>
-<li class="toctree-l2"><a class="reference internal" href="#running-finn-in-docker">Running FINN in Docker</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#running-finn-in-docker">Running FINN in Docker</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#getting-an-interactive-shell-for-development-or-experimentation">Getting an interactive shell for development or experimentation</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#running-the-jupyter-notebooks">Running the Jupyter notebooks</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#running-the-test-suite-directly">Running the test suite directly</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#running-the-test-suite-using-jenkins">Running the test suite using Jenkins</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="source_code.html">Source Code</a></li>
@@ -171,6 +177,50 @@
 <div class="section" id="running-finn-in-docker">
 <h2>Running FINN in Docker<a class="headerlink" href="#running-finn-in-docker" title="Permalink to this headline">¶</a></h2>
 <p>We use Docker extensively for developing and deploying FINN. If you are not familiar with Docker, there are many excellent <a class="reference external" href="https://docker-curriculum.com/">online resources</a> to get started. There is a Dockerfile in the root of the repository, as well as a <cite>run-docker.sh</cite> script that can be launched in the following modes:</p>
+<div class="section" id="getting-an-interactive-shell-for-development-or-experimentation">
+<h3>Getting an interactive shell for development or experimentation<a class="headerlink" href="#getting-an-interactive-shell-for-development-or-experimentation" title="Permalink to this headline">¶</a></h3>
+<dl class="simple">
+<dt>::</dt><dd><p>sh run_docker.sh</p>
+</dd>
+</dl>
+<p>Simply running sh run-docker.sh without any additional arguments will clone the dependency repos, create a Docker container and give you a terminal with you can use for development for experimentation.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>the Docker container is spawned with the <cite>–rm</cite> option, so make sure that any important files you created inside the container are either in the /workspace/finn folder (which is mounted from the host computer) or otherwise backed up.</p>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p><strong>Develop from host, run inside container:</strong> The FINN repository directory will be mounted from the host, so that you can use a text editor on your host computer to develop and the changes will be reflected directly inside the container.</p>
+</div>
+</div>
+<div class="section" id="running-the-jupyter-notebooks">
+<h3>Running the Jupyter notebooks<a class="headerlink" href="#running-the-jupyter-notebooks" title="Permalink to this headline">¶</a></h3>
+<dl class="simple">
+<dt>::</dt><dd><p>sh run-docker.sh notebook</p>
+</dd>
+</dl>
+<p>This will launch the Jupyter notebook server inside a Docker container, and print a link on the terminal that you can open in your browser to run the FINN notebooks or create new ones.
+.. note:: The link will look something like this (the token you get will be different):</p>
+<blockquote>
+<div><p><a class="reference external" href="http://127.0.0.1:8888/?token=f5c6bd32ae93ec103a88152214baedff4ce1850d81065bfc">http://127.0.0.1:8888/?token=f5c6bd32ae93ec103a88152214baedff4ce1850d81065bfc</a></p>
+</div></blockquote>
+<p>The run-docker.sh script forwards ports 8888 for Jupyter and 8081 for Netron, and launches the notebook server with appropriate arguments.</p>
+</div>
+<div class="section" id="running-the-test-suite-directly">
+<h3>Running the test suite directly<a class="headerlink" href="#running-the-test-suite-directly" title="Permalink to this headline">¶</a></h3>
+<dl class="simple">
+<dt>::</dt><dd><p>sh run-docker.sh test</p>
+</dd>
+</dl>
+<p>FINN comes with a set of tests which can be launched using the command above. Note that some of the tests involve extra compilation and the entire test suite may take some time to complete.</p>
+</div>
+<div class="section" id="running-the-test-suite-using-jenkins">
+<h3>Running the test suite using Jenkins<a class="headerlink" href="#running-the-test-suite-using-jenkins" title="Permalink to this headline">¶</a></h3>
+<dl class="simple">
+<dt>::</dt><dd><p>sh run-docker.sh jenkins</p>
+</dd>
+</dl>
+</div>
 </div>
 </div>
 

docs/finn/_build/html/index.html

@@ -160,7 +160,7 @@
 <ul class="simple">
 <li><p>The FINN project, which is an experimental framework from Xilinx Research Labs to explore deep neural network inference on FPGAs. It specifically targets quantized neural networks, with emphasis on generating dataflow-style architectures customized for each network. It includes tools for training quantized neural networks such as Brevitas, the FINN compiler, and the finn-hlslib Vivado HLS library of FPGA components for QNNs. An overview of the project can be taken from the following graphic and details can be seen on the <a class="reference external" href="https://xilinx.github.io/finn/">FINN project homepage</a>.</p></li>
 </ul>
-<a class="reference internal image-reference" href="_images/finn-stack.png"><img alt="_images/finn-stack.png" class="align-center" src="_images/finn-stack.png" style="width: 320.5px; height: 312.5px;" /></a>
+<a class="reference internal image-reference" href="_images/finn-stack.png"><img alt="_images/finn-stack.png" class="align-center" src="_images/finn-stack.png" style="width: 256.40000000000003px; height: 250.0px;" /></a>
 <ul class="simple">
 <li><p>The repository, this Read the Docs website corresponds to. It is about the FINN compiler, which is the centerpiece of the FINN project. The GitHub repository can be viewed using the link in the upper right corner. To learn more about the FINN compiler, use this website and for a hands-on experience the repository contains some Jupyter notebooks which can be found under this <a class="reference external" href="https://github.com/Xilinx/finn/tree/dev/notebooks">link</a>.</p></li>
 </ul>

docs/finn/getting_started.rst

@@ -17,3 +17,39 @@ Requirements
 Running FINN in Docker
 ======================
 We use Docker extensively for developing and deploying FINN. If you are not familiar with Docker, there are many excellent `online resources <https://docker-curriculum.com/>`_ to get started. There is a Dockerfile in the root of the repository, as well as a `run-docker.sh` script that can be launched in the following modes:
+
+Getting an interactive shell for development or experimentation
+***************************************************************
+::
+  sh run_docker.sh
+   
+Simply running sh run-docker.sh without any additional arguments will clone the dependency repos, create a Docker container and give you a terminal with you can use for development for experimentation.
+
+.. warning:: the Docker container is spawned with the `--rm` option, so make sure that any important files you created inside the container are either in the /workspace/finn folder (which is mounted from the host computer) or otherwise backed up.
+
+.. note:: **Develop from host, run inside container:** The FINN repository directory will be mounted from the host, so that you can use a text editor on your host computer to develop and the changes will be reflected directly inside the container.
+
+Running the Jupyter notebooks
+*****************************
+::
+  sh run-docker.sh notebook
+
+This will launch the Jupyter notebook server inside a Docker container, and print a link on the terminal that you can open in your browser to run the FINN notebooks or create new ones. 
+.. note:: The link will look something like this (the token you get will be different):
+          http://127.0.0.1:8888/?token=f5c6bd32ae93ec103a88152214baedff4ce1850d81065bfc
+
+The run-docker.sh script forwards ports 8888 for Jupyter and 8081 for Netron, and launches the notebook server with appropriate arguments.
+
+Running the test suite directly
+*******************************
+::
+  sh run-docker.sh test
+
+FINN comes with a set of tests which can be launched using the command above. Note that some of the tests involve extra compilation and the entire test suite may take some time to complete.  
+
+Running the test suite using Jenkins
+************************************
+::
+  sh run-docker.sh jenkins
+       
+

docs/finn/index.rst

@@ -17,7 +17,7 @@ What is FINN?
 * The FINN project, which is an experimental framework from Xilinx Research Labs to explore deep neural network inference on FPGAs. It specifically targets quantized neural networks, with emphasis on generating dataflow-style architectures customized for each network. It includes tools for training quantized neural networks such as Brevitas, the FINN compiler, and the finn-hlslib Vivado HLS library of FPGA components for QNNs. An overview of the project can be taken from the following graphic and details can be seen on the `FINN project homepage <https://xilinx.github.io/finn/>`_.
 
 .. image:: ../img/finn-stack.png
-   :scale: 50%
+   :scale: 40%
    :align: center
 
 * The repository, this Read the Docs website corresponds to. It is about the FINN compiler, which is the centerpiece of the FINN project. The GitHub repository can be viewed using the link in the upper right corner. To learn more about the FINN compiler, use this website and for a hands-on experience the repository contains some Jupyter notebooks which can be found under this `link <https://github.com/Xilinx/finn/tree/dev/notebooks>`_.