diff --git a/docs/development/environment.rst b/docs/development/environment.rst new file mode 100644 index 00000000..785e90fd --- /dev/null +++ b/docs/development/environment.rst @@ -0,0 +1,177 @@ +.. _sec-development-environment: + +Setting up a Development environment +==================================== + +.. _sec-development-environment-source: + +Obtaining, building and running the source +------------------------------------------ + +This describes the general steps in obtaining, building and running. OS specific instructions can be found +below. + + * Prerequisites: + + * `Python 2.7 `_ including ``pip``, ``setuptools`` and ``virtualenv`` + * `Git `_ + + * Checkout the OctoPrint sources from their Git repository: ``git clone https://github.com/foosel/OctoPrint.git`` + * Create a virtual environment in the checkout folder to use for installing and running OctoPrint and its + dependencies (this avoids potential versioning issues for the dependencies with system wide installed + instances): ``virtualenv venv`` + * Activate the virtual environment: ``source venv/bin/activate`` (might differ per your platform/OS) + * Update ``pip`` in the virtual environment: ``pip install --upgrade pip`` + * Install OctoPrint in `"editable" mode `_, + including its regular *and* development dependencies: ``pip install -e .[develop]`` + +.. _sec-development-environment-source-linux: + +Linux +..... + +This assumes you'll host your OctoPrint development checkout at ``~/devel/OctoPrint``. If you want to use a different +location, please substitute accordingly. + +First make sure you have python including its header files, pip, setuptools, virtualenv, git and some build requirements +installed: + + * On apt based distributions (e.g. Debian, Ubuntu, ...): + + .. code-block:: none + + sudo apt-get install python python-pip python-dev python-setuptools python-virtualenv git libyaml-dev build-essential + +.. todo:: + + Using a Linux distribution that doesn't use ``apt``? Please send a + `Pull Request `_ to get the necessary + steps into this guide! + +Then: + +.. code-block:: none + + cd ~/devel + git clone https://github.com/foosel/OctoPrint.git + cd OctoPrint + virtualenv venv + source ./venv/bin/activate + pip install --upgrade pip + pip install -e .[develop] + +You can then start OctoPrint via ``~/devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual +environment. + +.. _sec-development-environment-windows: + +Windows +....... + +This assumes you'll host your OctoPrint development checkout at ``C:\Devel\OctoPrint``. If you want to use a different +location, please substitute accordingly. + +First download & install: + + * `Python 2.7.12 Windows x86 MSI installer `_ + + * make sure to have the installer add Python to the ``PATH`` and have it install ``pip`` too + + * `Microsoft Visual C++ Compiler for Python 2.7 `_ + * `Git for Windows `_ + +Open the Git Bash you just installed and in that: + +.. code-block:: none + + pip install virtualenv + cd /c/Devel + git clone https://github.com/foosel/OctoPrint.git + cd OctoPrint + virtualenv venv + source ./venv/bin/activate + pip install --upgrade pip + pip install -e .[develop] + +You can then start OctoPrint via ``/c/Devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual +environment. + +.. _sec-development-environment-mac: + +Mac OS X +........ + +.. note:: + + This guide is based on the `Setup Guide for Mac OS X on OctoPrint's wiki `_. + Please report back if it works for you, due to lack of access to a Mac I cannot test it myself. Thanks. + +This assumes you'll host your OctoPrint development checkout at ``~/devel/OctoPrint``. If you want to use a different +location, please substitute accordingly. + +You'll need a user account with administrator privileges. + + * Install the latest version of Xcode suitable for your OS. For example, OS X 10.11 (El Capitan) requires Xcode 7. + * Install Xcode's command line tools: + + * ``xcode-select --install`` + * ``sudo xcodebuild`` (ensure the license was accepted) + * If you have more than one Xcode installed: ``sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`` + + * Install Homebrew and use that to install Python: + + * ``ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`` + * ``brew install python`` + + * Install `virtualenv `_ + + * ``pip install virtualenv`` + + * Install OctoPrint + + .. code-block:: none + + cd ~/devel + git clone https://github.com/foosel/OctoPrint.git + cd OctoPrint + virtualenv venv + source venv/bin/activate + pip install -e .[develop] + +You can then start OctoPrint via ``~/devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual +environment. + +.. _sec-development-environment-ides: + +IDE Setup +--------- + +.. todo:: + + Using another IDE than the ones below? Please send a + `Pull Request `_ to get the necessary + steps into this guide! + +.. _sec-development-environment-ides-pycharm: + +PyCharm +....... + + - "File" > "Open ...", select OctoPrint checkout folder (e.g. ``~/devel/OctoPrint`` or ``C:\Devel\OctoPrint``) + - "File" > "Settings ..." > "Project: OctoPrint" > "Project Interpreter" > "Add local ...", select OctoPrint venv + folder (e.g. ``~/devel/OctoPrint/venv`` or ``C:\Devel\OctoPrint\venv``) + - Right click "src" in project tree, mark as source folder + - Add Run/Debug Configuration, select "Python": + + * Name: OctoPrint server + * Script: path to ``run`` in the OctoPrint checkout folder (e.g. ``~/devel/OctoPrint/run`` or ``C:\Devel\OctoPrint\run``) + * Script parameters: ``--debug`` + * Project: ``OctoPrint`` + * Python interpreter: the ``venv`` local virtual environment + * Working directory: the OctoPrint checkout folder (e.g. ``~/devel/OctoPrint`` or ``C:\Devel\OctoPrint``) + +.. note:: + + Make sure you are running a PyCharm version of 2016.1 or later, or manually fix + `a debugger bug contained in earlier versions `_ or plugin management + will not work in your developer install when running OctoPrint from PyCharm in debug mode. diff --git a/docs/development/index.rst b/docs/development/index.rst index 7d24a843..8b303859 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -4,183 +4,8 @@ Development ########### -.. contents:: - :local: +.. toctree:: + :maxdepth: 3 -.. _sec-development-environment: - -Setting up a Development environment -==================================== - -.. _sec-development-environment-source: - -Obtaining, building and running the source ------------------------------------------- - -This describes the general steps in obtaining, building and running. OS specific instructions can be found -below. - - * Prerequisites: - - * `Python 2.7 `_ including ``pip``, ``setuptools`` and ``virtualenv`` - * `Git `_ - - * Checkout the OctoPrint sources from their Git repository: ``git clone https://github.com/foosel/OctoPrint.git`` - * Create a virtual environment in the checkout folder to use for installing and running OctoPrint and its - dependencies (this avoids potential versioning issues for the dependencies with system wide installed - instances): ``virtualenv venv`` - * Activate the virtual environment: ``source venv/bin/activate`` (might differ per your platform/OS) - * Update ``pip`` in the virtual environment: ``pip install --upgrade pip`` - * Install OctoPrint in `"editable" mode `_, - including its regular *and* development dependencies: ``pip install -e .[develop]`` - -.. _sec-development-environment-source-linux: - -Linux -..... - -This assumes you'll host your OctoPrint development checkout at ``~/devel/OctoPrint``. If you want to use a different -location, please substitute accordingly. - -First make sure you have python including its header files, pip, setuptools, virtualenv, git and some build requirements -installed: - - * On apt based distributions (e.g. Debian, Ubuntu, ...): - - .. code-block:: none - - sudo apt-get install python python-pip python-dev python-setuptools python-virtualenv git libyaml-dev build-essential - -.. todo:: - - Using a Linux distribution that doesn't use ``apt``? Please send a - `Pull Request `_ to get the necessary - steps into this guide! - -Then: - -.. code-block:: none - - cd ~/devel - git clone https://github.com/foosel/OctoPrint.git - cd OctoPrint - virtualenv venv - source ./venv/bin/activate - pip install --upgrade pip - pip install -e .[develop] - -You can then start OctoPrint via ``~/devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual -environment. - -.. _sec-development-environment-windows: - -Windows -....... - -This assumes you'll host your OctoPrint development checkout at ``C:\Devel\OctoPrint``. If you want to use a different -location, please substitute accordingly. - -First download & install: - - * `Python 2.7.12 Windows x86 MSI installer `_ - - * make sure to have the installer add Python to the ``PATH`` and have it install ``pip`` too - - * `Microsoft Visual C++ Compiler for Python 2.7 `_ - * `Git for Windows `_ - -Open the Git Bash you just installed and in that: - -.. code-block:: none - - pip install virtualenv - cd /c/Devel - git clone https://github.com/foosel/OctoPrint.git - cd OctoPrint - virtualenv venv - source ./venv/bin/activate - pip install --upgrade pip - pip install -e .[develop] - -You can then start OctoPrint via ``/c/Devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual -environment. - -.. _sec-development-environment-mac: - -Mac OS X -........ - -.. note:: - - This guide is based on the `Setup Guide for Mac OS X on OctoPrint's wiki `_. - Please report back if it works for you, due to lack of access to a Mac I cannot test it myself. Thanks. - -This assumes you'll host your OctoPrint development checkout at ``~/devel/OctoPrint``. If you want to use a different -location, please substitute accordingly. - -You'll need a user account with administrator privileges. - - * Install the latest version of Xcode suitable for your OS. For example, OS X 10.11 (El Capitan) requires Xcode 7. - * Install Xcode's command line tools: - - * ``xcode-select --install`` - * ``sudo xcodebuild`` (ensure the license was accepted) - * If you have more than one Xcode installed: ``sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`` - - * Install Homebrew and use that to install Python: - - * ``ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`` - * ``brew install python`` - - * Install `virtualenv `_ - - * ``pip install virtualenv`` - - * Install OctoPrint - - .. code-block:: none - - cd ~/devel - git clone https://github.com/foosel/OctoPrint.git - cd OctoPrint - virtualenv venv - source venv/bin/activate - pip install -e .[develop] - -You can then start OctoPrint via ``~/devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual -environment. - -.. _sec-development-environment-ides: - -IDE Setup ---------- - -.. todo:: - - Using another IDE than the ones below? Please send a - `Pull Request `_ to get the necessary - steps into this guide! - -.. _sec-development-environment-ides-pycharm: - -PyCharm -....... - - - "File" > "Open ...", select OctoPrint checkout folder (e.g. ``~/devel/OctoPrint`` or ``C:\Devel\OctoPrint``) - - "File" > "Settings ..." > "Project: OctoPrint" > "Project Interpreter" > "Add local ...", select OctoPrint venv - folder (e.g. ``~/devel/OctoPrint/venv`` or ``C:\Devel\OctoPrint\venv``) - - Right click "src" in project tree, mark as source folder - - Add Run/Debug Configuration, select "Python": - - * Name: OctoPrint server - * Script: path to ``run`` in the OctoPrint checkout folder (e.g. ``~/devel/OctoPrint/run`` or ``C:\Devel\OctoPrint\run``) - * Script parameters: ``--debug`` - * Project: ``OctoPrint`` - * Python interpreter: the ``venv`` local virtual environment - * Working directory: the OctoPrint checkout folder (e.g. ``~/devel/OctoPrint`` or ``C:\Devel\OctoPrint``) - -.. note:: - - Make sure you are running a PyCharm version of 2016.1 or later, or manually fix - `a debugger bug contained in earlier versions `_ or plugin management - will not work in your developer install when running OctoPrint from PyCharm in debug mode. + environment.rst + virtual_printer.rst diff --git a/docs/development/virtual_printer.rst b/docs/development/virtual_printer.rst new file mode 100644 index 00000000..479cdc19 --- /dev/null +++ b/docs/development/virtual_printer.rst @@ -0,0 +1,116 @@ +.. _sec-development-virtual-printer: + +Setting up the virtual printer for debugging +============================================ + +OctoPrint includes, by default, a virtual printer plugin. This plugin allows you to debug OctoPrint's serial +communication without connecting to an actual printer. Furthermore, it is possible to create certain edge conditions +that may be hard to reproduce with a real printer. + +.. _sec-development-virtual-printer-enable: + +Enabling the virtual printer +---------------------------- + +The virtual printer is enabled by editing OctoPrint's config.yaml file. Details on the configuration file can +be found in the full :ref:`config.yaml documentation `. + +The steps to take are as follows: + +* Find config.yaml in the OctoPrint settings folder. Usually in ``~/.octoprint`` on Linux, in ``%APPDATA%/OctoPrint`` on Windows and in ``~/Library/Application Support/OctoPrint`` on MacOS. +* Add or extend the ``devel`` section with: + +.. code-block:: yaml + + devel: + virtualPrinter: + enabled: true + +* Restart OctoPrint. +* In the connection panel, a new option will appear in the Serial Port dropdown labeled ``VIRTUAL``. +* Select this option and click ``connect``. +* The virtual printer is now active. + +.. _sec-development-virtual-printer-config: + +Virtual printer configuration options +------------------------------------- + +The config.yaml file has many configuration options for the virtual printer that allow you to fine-tune its behavior. + +Please see the relevant :ref:`config.yaml section ` for the full details. + +.. _sec-development-virtual-printer-log: + +Log file +-------- + +Once activated, the virtual printer will log all serial communication in the ``plugin_virtual_printer_serial.log`` file +that can be found in the OctoPrint settings folder. + +.. _sec-development-virtual-printer-debug: + +Debug commands +-------------- + +You can simulate certain conditions and communications through the terminal tab in OctoPrint's interface. + +All commands start with ``!!DEBUG:`` and are followed by the command you want to execute. For instance, sending +``!!DEBUG:action_disconnect`` will disconnect the printer. Sending ``!!DEBUG`` without command will show a help +message with all the available commands. + +Action Triggers +............... + +``action_pause`` +Sends a "// action:pause" action trigger to the host. + +``action_resume`` +Sends a "// action:resume" action trigger to the host. + +``action_disconnect`` +Sends a "// action:disconnect" action trigger to the host. + +``action_custom [ ]`` +Sends a custom "// action: " action trigger to the host. + +Communication Errors +.................... + +``dont_answer`` +Will not acknowledge the next command. + +``go_awol`` +Will completely stop replying. + +``trigger_resend_lineno`` +Triggers a resend error with a line number mismatch + +``trigger_resend_checksum`` +Triggers a resend error with a checksum mismatch + +``drop_connection`` +Drops the serial connection + +``prepare_ok `` +Will cause to be enqueued for use, will be used instead of actual "ok" + +Reply Timing / Sleeping +....................... +``sleep `` +Sleep s + +``sleep_after `` +Sleeps s after each execution of + +``sleep_after_next `` +Sleeps s after execution of next + +Misc +.... + +``help`` +Show the available commands. + +``send `` +Sends back