.. Installation guide, describes setup for local development and opperation on mobile devices

#################
Developer's Guide
#################

.. contents::
   :depth: 5

.. toctree::
   :maxdepth: 2

   modules

Installation
============

To install the code base for local development, you'll need to make sure you have a JDK, 
`NodeJS <https://nodejs.org/en/download/>`_, and React Native installed. React Native can 
be installed using npm once NodeJS has been installed:

.. code-block:: bash

   npm install -g react-native-cli

If you want to be able to run the application in the iOS and Android emulators, you will also
need to install `XCode <https://developer.apple.com/download/more/>`_ and 
`Android Studio <https://developer.android.com/studio>`_. You will need to make sure that you 
create an Android virtual device before you can launch an Android emulator. There is a good 
tutorial on how to do that `here <https://docs.expo.io/versions/latest/workflow/android-studio-emulator/>`_.

Finally, clone the repo, cd into the project directory and run

.. code-block:: bash

   npm install

This will install all of the required npm libraries for the application.

If you want to edit the documentation, you will need JSDoc and Sphinx:

.. code-block:: bash

   npm install -g jsdoc
   pip install sphinx-js

The application can be run like any other React Native application.

iOS

.. code-block:: bash

   react-native run-ios

Android

.. code-block:: bash

   react-native run-android

Ensure that you start the Android emulator before running the ``run-android`` command. The iOS emulator 
will automatically start when ``run-ios`` is called.

Documentation
=============

Documentation should be written using `reStructuredText
<http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
Standalone doc pages should be put into ``docs/source`` so the docstrings end up in the
docs site.  Pages won't show up on the site unless they are
linked from another page (that is linked from another page...) which is eventually linked
to from index.rst. 

Creating the docs (modeled on `this <https://github.com/daler/sphinxdoc-test/blob/master/README.rst>`_)
--------------------------------------------------------------------------------------------------------------

On your local machine create another directory in the directory that contains the main
application directory. I.e. if you cloned the repo into ``my_workspace/MobileStats``, then create a second
directory ``my_workspace/MobileStats_docs``. eg:

.. code-block:: bash

   $ pwd
   /home/username/my_workspace
   $ ls MobileStats*
   MobileStats:
   ...
   MobileStats-docs:
   ...


The code repository, ``MobileStats/``, is where modifications are made.
``MobileStats-docs/`` is generated when the docs are built.

The docs directory ``MobileStats-docs/`` should contain a directory called
``html`` which is a special MobileStats git repository that is set up
to only have a special single branch: ``gh-pages``.  This is where the documentation
builder places its outputs.  To create such a directory for the first time:

.. code-block:: bash

  mkdir MobileStats-docs  #if needed - should be next to MobileStats as above 
  cd MobileStats-docs
  git clone https://github.niaid.nih.gov/dommerjl/mobile-stats-app.git html
  cd html
  git checkout gh-pages
  git symbolic-ref HEAD refs/heads/gh-pages


To build the docs you will need to pip install the Sphinx library::

  sphinx_rtd_theme

The docs are then built with

.. code-block:: bash

   cd docs # pwd is now MobileStats/docs
   make html # we're only generating a website.


This will build the docs into ``MobileStats_docs/html``. The website can be viewed in the ``MobileStats-docs/html/`` directory 
by running:

.. code-block:: bash

   # pwd is MobileStats-docs/html/
   python -m SimpleHTTPServer 8000

to examine the docs as they are created. Docs can be viewed at 127.0.0.1:8000.

Once you are happy with the documentation you can publish it on github by
running:

.. code-block:: bash

   # pwd is MobileStats-docs/html/
   git commit -a -m "rebuilt docs"
   git push origin gh-pages