<commit_before>Developer Guide
===============

Girder is a platform-centric web application whose client and server are very
loosely coupled. As such, development of Girder can be divided into the server
(a CherryPy-based Python module) and the primary client (a Backbone-based) web
client. This section is intended to get prospective contributors to understand
the tools used to develop Girder.

Configuring Your Development Environment
----------------------------------------

In order to develop Girder, you should first refer to :doc:`prerequisites <prerequisites>`, `virtual environment <installation.html#creating-a-virtual-environment>`__, `install from Git <installation.html#install-from-git-repository>`__, and `run <installation.html#run>`__ sections to setup a basic local development environment.

Next, you should install the Python development dependencies with pip, to
provide helpful development tools and to allow the test suite to run: ::

    pip install -r requirements-dev.txt

Install front-end web client development dependencies. This will install npm modules eslint and pug-lint, which are needed to run unit tests. This will also build the web client code: ::

    girder-install web --dev

For more options for building the web client, run: ::

    girder-install web --help


Vagrant
^^^^^^^

A shortcut to going through the installation steps for development is to use
`Vagrant <https://www.vagrantup.com>`_ to setup the environment on a
`VirtualBox <https://www.virtualbox.org>`_ virtual machine. To setup this
environment run ``vagrant up`` in the root of the repository. This will spin up
and provision a virtual machine, provided you have Vagrant and VirtualBox
installed. Vagrant uses `Ansible <https://ansible.com>`_ for provisioning Girder and its various
dependencies.

.. seealso::

   For more information on provisioning Girder, see :doc:`provisioning`.


During Development
------------------

Once Girder is started via ``girder-server``, the server
will reload itself whenever a Python file is modified.

If you are doing front-end development, it's much faster to use a *watch* process to perform
automatic fast rebuilds of your code whenever you make changes to source files.

If you are making changes to Girder's core web client, run the following watch command: ::

    girder-install web --watch

If you are developing a web client of a plugin, run: ::

    girder-install web --watch-plugin your_plugin_name

With ``watch`` option, *sourcemaps* will be generated, which helps debugging front-end code in browser.
When you want to end the watch process, press Ctrl+C (or however you would normally terminate a
process in your terminal).


Utilities
---------

Girder has a set of utility modules and classes that provide handy extractions
for certain functionality. Detailed API documentation can be found :ref:`here <api-docs-utility>`.

Configuration Loading
^^^^^^^^^^^^^^^^^^^^^
<commit_msg>Add documentation for girder-shell<commit_after>Developer Guide
===============

Girder is a platform-centric web application whose client and server are very
loosely coupled. As such, development of Girder can be divided into the server
(a CherryPy-based Python module) and the primary client (a Backbone-based) web
client. This section is intended to get prospective contributors to understand
the tools used to develop Girder.

Configuring Your Development Environment
----------------------------------------

In order to develop Girder, you should first refer to :doc:`prerequisites <prerequisites>`, `virtual environment <installation.html#creating-a-virtual-environment>`__, `install from Git <installation.html#install-from-git-repository>`__, and `run <installation.html#run>`__ sections to setup a basic local development environment.

Next, you should install the Python development dependencies with pip, to
provide helpful development tools and to allow the test suite to run: ::

    pip install -r requirements-dev.txt

Install front-end web client development dependencies. This will install npm modules eslint and pug-lint, which are needed to run unit tests. This will also build the web client code: ::

    girder-install web --dev

For more options for building the web client, run: ::

    girder-install web --help


Vagrant
^^^^^^^

A shortcut to going through the installation steps for development is to use
`Vagrant <https://www.vagrantup.com>`_ to setup the environment on a
`VirtualBox <https://www.virtualbox.org>`_ virtual machine. To setup this
environment run ``vagrant up`` in the root of the repository. This will spin up
and provision a virtual machine, provided you have Vagrant and VirtualBox
installed. Vagrant uses `Ansible <https://ansible.com>`_ for provisioning Girder and its various
dependencies.

.. seealso::

   For more information on provisioning Girder, see :doc:`provisioning`.


During Development
------------------

Once Girder is started via ``girder-server``, the server
will reload itself whenever a Python file is modified.

If you are doing front-end development, it's much faster to use a *watch* process to perform
automatic fast rebuilds of your code whenever you make changes to source files.

If you are making changes to Girder's core web client, run the following watch command: ::

    girder-install web --watch

If you are developing a web client of a plugin, run: ::

    girder-install web --watch-plugin your_plugin_name

With ``watch`` option, *sourcemaps* will be generated, which helps debugging front-end code in browser.
When you want to end the watch process, press Ctrl+C (or however you would normally terminate a
process in your terminal).

Girder Shell
^^^^^^^^^^^^

To test various functionality in a typical REPL (Python, IPython, etc) some bootstrapping
is required to configure the Girder server. This sets up an "embedded" server, meaning no TCP ports
are actually bound but requests can still be performed via Python. Bootstrapping the server
involves running ``girder.utility.server.configureServer`` with the plugins to be enabled.

Girder provides a utility script for entering into a shell with the server preconfigured. Once
Girder is installed the script can be run using ``girder-shell`` which optionally takes a comma
separated list of plugins to enable.

Utilities
---------

Girder has a set of utility modules and classes that provide handy extractions
for certain functionality. Detailed API documentation can be found :ref:`here <api-docs-utility>`.

Configuration Loading
^^^^^^^^^^^^^^^^^^^^^

{'fraction_non_alphanumeric': 0.09245110024449878, 'fraction_numerical': 0.0, 'mean_word_length': 4.227635782747604, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2807372', 'n_tokens_mistral': 1671, 'n_tokens_neox': 1595, 'n_words': 850}