###########
Development
###########

.. toctree::
   :maxdepth: 3

.. _dev_env:

***********************
Development environment
***********************

It is convenient to setup a separate virtual environment:

Using pipenv
============

1. Install pipenv::

	$ pip install pipenv
	
2. Navigate to the shobnetpy folder::

	$ cd shobnetpy
	
3. Create virtual environment::

	$ pipenv shell

4. Install requirements::

	$ pipenv install
	$ pipenv install -r requirements_dev.txt
	
	
***********
Style Guide
***********


- Code should stick to PEP 8 (https://peps.python.org/pep-0008/) 


Documenting code
================

- Docstrings in `numpy format <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_

- Members starting with an underscore (_) will not be included in the docs.


String formatting
=================

The use of `f-strings <https://realpython.com/python-f-strings/>`_ has precedence over `format()` and the modulo operator.
F-strings are `easier to read and perform better <https://realpython.com/python-string-formatting/>`_.
Exceptions apply when lazy evaluation of strings is required. F-Strings also allow format specifiers as 2nd argument
after a ":" within the curly brackets.

::

	message = (
		f"Number of retrieved rows ({len(mz_df)}) for BC={gtvalue}, OT={otvalue} and "
		f"BAC={bakvalue} deviates from requested number ({samplesize:5d}) by more than 1!"
	)

        
.. include:: 
	development/testing.rst

*******************
Documentation Guide
*******************

SHoBNetPy uses sphinx to document concepts, modules, use instructions, API and so on.

Resources:

`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_

`reStructuredText Directives <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`_

- Docs for new modules can be generated by

  ::

	
	
	# Windows
	cd shobnetpy\doc\sphinx
	sphinx-apidoc.exe -o .\source\application\api\ ..\shobnetpy\
	
	#*unix
	cd shobnetpy/doc/sphinx
	sphinx-apidoc -o ./source/application/api/ ../shobnetpy/
  
  .. note::
	You may need to remove existing subpackage rst files for new modules to be added. Then, replace
	`Submodules` with `.. contents::` in teh new rst files. Generated files modules.rst, shopnetpy.rst and setup.rst
	can be deleted to avoid warnings (they are not linked).

- Heading hierarchy:

	1. 
		::
		
			#########
			1st level
			#########
	
	2. 
		::
		
			*********
			2nd level 
			*********
			
	3. 
		::	
		
			3rd level
			=========
			
	4.
		::
		
			4th level
			---------
			
Building documentation
======================

- HTML pages

	::

  		cd <path to shobnetpy>/doc/sphinx
  		make html


	For windows, `make.bat html` should work.
	  	
- Docx document

	::
  
  		cd <path to shobnetpy>/doc/sphinx
  		make docx


In order for this to work, either ensure to be in the shopnetpy (see :ref:`dev_env`)
virtual environment or set the path to the `sphinx-build` executable manually
by

::

	set SPHINXBUILD=<path to shobnetpy>\.venv\Scripts\sphinx-build.exe

in Windows command line before running the above `make`-commands.

*******	
Logging
*******

See :ref:`concepts_logging_implementation`.


******************
3rd Party Packages
******************


shapely
=======

= `Shapely User Manual <https://shapely.readthedocs.io/en/stable/manual.html>`_


mesa
====

= `Mesa project website <https://mesa.readthedocs.io/stable/>`_


mesa=geo
========

= `Mesa-Geo project website <https://mesa=geo.readthedocs.io/stable/>`_

networkx
========

= `NetworkX = Network Analysis in python <https://networkx.org/documentation/stable/index.html>`_

pytreemap
=========

= `pytreemap project website <https://github.com/GavinPHR/pytreemap>`_

dynaconf
========

= `dynaconf project website <https://www.dynaconf.com/>`_


scipy
=====

= `SciPy website <https://scipy.org/>`_

qgispy
======

= `QGIS Python API documentation <https://qgis.org/pyqgis/master/>`_


**********************
Release Workflow (WiP)
**********************

1. Testing

2. Update dependencies

	1. requirements.txt
	
	2. poetry

3. Update documentation

	1. Update API
	
	2. Update settings
	
4. Commit to gitlab

5. Publish new version