From 6e6051e44f80a3e155da16c611280e44b158d611 Mon Sep 17 00:00:00 2001
From: Dilawar Singh <dilawars@ncbs.res.in>
Date: Tue, 2 May 2017 13:03:32 +0530
Subject: [PATCH] Gettting docs from Malav pull request. Pull request is
revered back.
---
docs/README.txt | 19 +-
docs/readthedocs-pip-requirements.txt | 1 +
docs/source/conf.py | 20 +-
docs/source/install/install.rst | 35 +--
.../user/py/introduction/changes/index.rst | 4 +
docs/source/user/py/introduction/index.rst | 9 +
.../user/py/introduction/install/index.rst | 208 ++++++++++++++++++
.../py/introduction/known_issues/index.rst | 9 +
.../py/introduction/release_notes/index.rst | 4 +
9 files changed, 248 insertions(+), 61 deletions(-)
create mode 100644 docs/source/user/py/introduction/changes/index.rst
create mode 100644 docs/source/user/py/introduction/index.rst
create mode 100644 docs/source/user/py/introduction/install/index.rst
create mode 100644 docs/source/user/py/introduction/known_issues/index.rst
create mode 100644 docs/source/user/py/introduction/release_notes/index.rst
diff --git a/docs/README.txt b/docs/README.txt
index 6205b2ca..5145c53c 100644
--- a/docs/README.txt
+++ b/docs/README.txt
@@ -1,18 +1 @@
-This is the MOOSE documentation directory. The documentation is grouped into
-the following directories:
-
- - user: This is for anyone wishing to learn/use MOOSE.
- This part of the documentation is encoded in Markdown format.
- - developer: If you wish to learn about MOOSE code, go here.
- - doxygen: Source code documentation generation.
- - markdown: This contains a quick introduction to Markdown itself.
- - images: These are images that are included in the user and developer
- documentation.
-
---------------------------------------------------------------------------------
-N.B.: This text file has Windows-style line endings (CR/LF) for easy
-viewing in Windows. We will try to keep the other text files here
-Windows-compatible (e.g.: *.markdown files), but we may slip.
-If you have difficulty viewing them in Notepad, try the inbuilt Wordpad
-editor, or better still, download a good text editor like Notepad++ or Geany.
---------------------------------------------------------------------------------
+The source code of documentation is ./source directory.
diff --git a/docs/readthedocs-pip-requirements.txt b/docs/readthedocs-pip-requirements.txt
index a2954e31..e05848ed 100644
--- a/docs/readthedocs-pip-requirements.txt
+++ b/docs/readthedocs-pip-requirements.txt
@@ -1 +1,2 @@
numpydoc
+mock
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 329de82e..92521adc 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -137,16 +137,6 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# of the sidebar.
html_logo = 'images/moose_logo.png'
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
@@ -270,7 +260,15 @@ texinfo_domain_indices = True
numpydoc_show_class_members = False
# autodoc options to mock MOOSE module
-autodoc_mock_imports = [ 'numpy' , 'moose.sbml' , 'moose.genesis' , 'moose.LIF' , 'moogli.extensions.moose' , 'extensions.moose', 'moose' , 'moose.SBML' , 'pylab' , 'moose.genesis' , 'datetime' , 'getpass' , 'h5py' , 'matplotlib' , 'squid' , 'PyQt4' , 'moogli' , 'moose.utils' , 'math' , 'SquidAxon' , '_moogli' , 'XRRRates' , 'neuroml.NeuroML' ,'neuroml' , 'rdesigneur' , 'pyplot' , 'gnuplot' , 'cm' , 'matplotlib.pyplot' , 'matplotlib.image' , 'matplotlib.cm' , 'shapes' , 'chemUtil.add_Delete_ChemicalSolver' ]
+autodoc_mock_imports = [ 'numpy' , 'moose.sbml' , 'moose.genesis' , 'moose.LIF'
+ , 'moogli.extensions.moose' , 'extensions.moose', 'moose' , 'moose.SBML'
+ , 'pylab' , 'moose.genesis' , 'datetime' , 'getpass' , 'h5py'
+ , 'matplotlib' , 'squid' , 'PyQt4' , 'moogli' , 'moose.utils'
+ , 'math' , 'SquidAxon' , '_moogli' , 'XRRRates' , 'neuroml.NeuroML'
+ ,'neuroml' , 'rdesigneur' , 'pyplot' , 'gnuplot' , 'cm'
+ , 'matplotlib.pyplot' , 'matplotlib.image' , 'matplotlib.cm' , 'shapes'
+ , 'chemUtil.add_Delete_ChemicalSolver'
+ ]
#include reference files
exclude_patterns = ['/docs/source/user/py/references/*.rst']
diff --git a/docs/source/install/install.rst b/docs/source/install/install.rst
index d0aafce9..a2dd15f0 100644
--- a/docs/source/install/install.rst
+++ b/docs/source/install/install.rst
@@ -5,7 +5,7 @@ Linux
^^^^^^
We recommend that you use our repositories hosted at `Open Build Service
-<http://build.opensuse.org>`_. We have packages for the following distributions
+<https://build.opensuse.org/package/show/home:moose/moose>`_. We have packages for the following distributions
- Debian 7.0, 8.0
- Ubuntu 12.04, 14.04, 15.04, 15.10, 16.04
@@ -25,22 +25,13 @@ to pick your distribution and follow instructions.
.. todo:: Packages for gentoo, Arch Linux
-Mac OSX
-^^^^^^^
-Download the ``dmg`` file from `here <https://github.com/BhallaLab/moose/releases/download/ghevar_3.0.2/Moose_3.0.2_OSX.dmg>`_.
-
-Alternatively, you can use ``homebrew`` to install ``moose``
+MacOSX support is not complete yet. Python-scripting interface can be installed on MaxOSX using ``homebrew``
::
$ brew install homebrew/science/moose
-Windows/Cygwin
-^^^^^^^^^^^^^^
-
-Coming soon...!
-
Building MOOSE
--------------
@@ -64,13 +55,6 @@ Or,
If you don't want lasest snapshot of ``MOOSE``, you can download other released
versions from `here <`https://github.com/BhallaLab/moose/releases>`_.
-Once you have downloaded the repository, ::
-
- $ cd moose
- $ git submodule update --init; git pull
- or
- $ sudo -E ./update-repository # This script updates the repository and its subrepositories recursively, located in moose folder
-
Install dependencies
^^^^^^^^^^^^^^^^^^^^
@@ -125,20 +109,6 @@ On ``OpenSUSE``
build moose
^^^^^^^^^^^
-Method 1: Using Makefile
-""""""""""""""""""""""""
-
-.. code-block:: bash
-
- $ cd moose-core
- $ make
- $ export PYTHONPATH="/homedir/moose-core/python"
- or
- $ ./build-moose-core #builds moose and sets the pythonpath in local_site_package_directory
-
-Method 2: Using cmake
-"""""""""""""""""""""
-
.. code-block:: bash
$ cd /to/moose/source/code
@@ -147,6 +117,7 @@ Method 2: Using cmake
$ cmake ..
$ make
$ ctest --output-on-failure # optional
+ $ sudo make install
This will build pyMOOSE (MOOSE's python extention), `ctest` will run few tests to
check if build process was successful.
diff --git a/docs/source/user/py/introduction/changes/index.rst b/docs/source/user/py/introduction/changes/index.rst
new file mode 100644
index 00000000..9a167f14
--- /dev/null
+++ b/docs/source/user/py/introduction/changes/index.rst
@@ -0,0 +1,4 @@
+Changes
+=======
+
+.. todo:: collect changes from OBS.
diff --git a/docs/source/user/py/introduction/index.rst b/docs/source/user/py/introduction/index.rst
new file mode 100644
index 00000000..b55005ae
--- /dev/null
+++ b/docs/source/user/py/introduction/index.rst
@@ -0,0 +1,9 @@
+Introduction
+============
+
+.. toctree::
+
+ install/index
+ release_notes/index
+ changes/index
+ known_issues/index
diff --git a/docs/source/user/py/introduction/install/index.rst b/docs/source/user/py/introduction/install/index.rst
new file mode 100644
index 00000000..888aede8
--- /dev/null
+++ b/docs/source/user/py/introduction/install/index.rst
@@ -0,0 +1,208 @@
+Installation
+============
+
+Use pre-built packages
+----------------------
+
+Linux
+^^^^^
+
+We recommend that you use our repositories hosted at `Open Build Service
+<http://build.opensuse.org>`_. We have packages for the following distributions
+
+- Debian 7.0, 8.0
+- Ubuntu 12.04, 14.04, 15.04, 15.10, 16.04
+- CentOS 6, 7
+- Fedora 20, 21, 22, 23
+- OpenSUSE 13.1, 13.2, Factory ARM, Leap 42.1, Tumbleweed
+- SLE 12, 12 SP1
+- RHEL 7
+- Scientific Linux 7
+
+Visit `this page
+<https://software.opensuse.org/download.html?project=home:moose&package=moose>`_
+pick you distribution and follow instructions.
+
+.. note::
+ ``moogli`` (tool to visualize network activity) is not available for CentOS-6.
+
+.. raw:: html
+ <iframe
+ src="http://software.opensuse.org/download/package.iframe?project=moose&package=moose"></iframe>
+
+.. todo:: Packages for gentoo, Arch Linux
+
+
+Mac OSX
+^^^^^^
+
+:strike:`Download the ``dmg`` file from `here <https://github.com/BhallaLab/moose/releases/download/ghevar_3.0.2/Moose_3.0.2_OSX.dmg>`_.` We no longer build `dmg` files.
+
+
+On MacOSX, `MOOSE` is available via `homebrew <https://brew.sh>`_.
+::
+ $ brew install homebrew/science/moose
+
+
+Windows/Cygwin
+^^^^^^^^^^^^^^
+
+Building MOOSE
+--------------
+
+In case your distribution is not listed on `our repository page
+<https://software.opensuse.org/download.html?project=home:moose&package=moose>`_
+, or if you want to build the lastest development code, read on.
+
+First, you need to get the source code. You can use ``git`` (clone the
+repository) or download snapshot of github repo by clicking on `this link
+<https://github.com/BhallaLab/moose/archive/master.zip>`_.::
+ $ git clone https://github.com/BhallaLab/moose
+
+Or,
+::
+ $ wget https://github.com/BhallaLab/moose/archive/master.zip
+ $ unzip master.zip
+
+If you don't want lasest snapshot of ``MOOSE``, you can download other released
+versions from here `https://github.com/BhallaLab/moose/releases`.
+
+Install dependencies
+~~~~~~~~~~~~~~~~~~~
+
+Next, you need to install required dependencies. Depending on your OS, names of
+following packages may vary.
+
+- cmake (version 2.8 or higher)
+- gsl-1.16 or higher `download <ftp://ftp.gnu.org/gnu/gsl/>`_.
+- libhdf5 development package e.g. `libhdf5-serial-dev` or `libhdf5-devel`
+- python development package e.g. `python-dev` or `python-devel`
+- numpy e.g. `python-numpy` or `numpy`
+
+Most of the dependencies can be installed using package manager.
+
+On ``Debian/Ubuntu``
+::
+ $ sudo apt-get install libhdf5-dev cmake libgsl0-dev libpython-dev python-numpy
+
+.. note::
+ Ubuntu 12.04 does not have required version of ``gsl`` (required 1.16 or
+ higher, available 1.15). On Ubuntu 16.04, package name is ``libgsl-dev``.
+
+On ``CentOS/Fedora/RHEL/Scientific Linux``
+::
+ $ sudo yum install hdf5-devel cmake libgsl-dev python-devel python-numpy
+
+On ``OpenSUSE``
+::
+ $ sudo zypper install hdf5-devel cmake libgsl-dev python-devel python-numpy
+
+Now use `cmake` to build moose
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. codeblock:: bash
+ $ cd /to/moose/source/code
+ $ mkdir _build
+ $ cd _build
+ $ cmake ..
+ $ make
+ $ ctest --output-on-failure # optional
+
+This will build pyMOOSE (MOOSE's python extention), `ctest` will run few tests to
+check if build process was successful.
+
+.. note::
+ To install MOOSE into non-standard directory, pass additional argument
+ `-DCMAKE_INSTALL_PREFIX=path/to/install/dir` to cmake
+ ::
+ $ cmake -DCMAKE_INSTALL_PREFIC=$HOME/.local ..
+
+ To use different version of python
+ ::
+ $ cmake -DPYTHON_EXECUTABLE=/opt/python3/bin/python3 ..
+
+After that installation is pretty easy
+::
+ $ sudo make install
+
+If everything went fine, you should be able to import moose in python shell.
+
+.. code-block:: python
+ import moose
+
+
+Graphical User Interface (GUI)
+------------------------------
+
+You can get the source of ``moose-gui`` from `here
+<https://github.com/BhallaLab/moose-gui>`_. You can download it either by
+clicking on `this link <https://github.com/BhallaLab/moose-gui/archive/master.zip>`_
+or by using ``git`` ::
+ $ git clone https://github.com/BhallaLab/moose-gui
+
+To be able to launch ``moose-gui``, you need to install some more packages
+
+- matplotlib
+- python-qt4
+
+On ``Ubuntu/Debian``, these can be installed with
+::
+ $ sudo apt-get install python-matplotlib python-qt4
+
+On ``CentOS/Fedora/RHEL``
+::
+ $ sudo yum install python-matplotlib python-qt4
+
+Now you can fire up the GUI
+::
+ $ cd /to/moose-gui
+ $ python mgui.py
+
+.. note::
+ If you have installed ``moose`` package, then GUI is launched by
+ running following commnad::
+ $ moose
+
+Building moogli
+---------------
+
+``moogli`` is subproject of ``MOOSE`` for visualizing models. More details can
+be found `here <http://moose.ncbs.res.in/moogli>`_.
+
+`Moogli` is part of `moose` package. Building moogli can be tricky because of
+multiple depednecies it has.
+
+
+To get the latest source code of ``moogli``, click on `this link <https://github.com/BhallaLab/moogli/archive/master.zip>`_.
+
+Moogli depends on ``OpenSceneGraph`` (version 3.2.0 or higher) which may not
+be easily available for your operating system.
+For this reason, we distribute required ``OpenSceneGraph`` with ``moogli``
+source code.
+
+Depending on distribution of your operating system, you would need following
+packages to be installed.
+
+On ``Ubuntu/Debian``
+::
+ $ sudo apt-get install python-qt4-dev python-qt4-gl python-sip-dev libqt4-dev
+
+On ``Fedora/CentOS/RHEL``
+::
+ $ sudo yum install sip-devel PyQt4-devel qt4-devel libjpeg-devel PyQt4
+
+On ``openSUSE``
+::
+ $ sudo zypper install python-sip python-qt4-devel libqt4-devel python-qt4
+
+After this, building and installing ``moogli`` should be as simple as
+::
+ $ cd /path/to/moogli
+ $ mkdir _build
+ $ cd _build
+ $ cmake ..
+ $ make
+ $ sudo make install
+
+If you run into troubles, please report it on our `github repository
+<https://github.com/BhallaLab/moose/issues>`_.
diff --git a/docs/source/user/py/introduction/known_issues/index.rst b/docs/source/user/py/introduction/known_issues/index.rst
new file mode 100644
index 00000000..0ad5cdd6
--- /dev/null
+++ b/docs/source/user/py/introduction/known_issues/index.rst
@@ -0,0 +1,9 @@
+Known issues
+============
+
+Full report can be found at the following places
+
+- Related to build, packages and documentation `https://github.com/BhallaLab/moose/issues`
+- Related to python interface of MOOSE `https://github.com/BhallaLab/moose-core/issues`
+- Related to MOOSE GUI `https://github.com/BhallaLab/moose-gui/issues`
+- Related to ``moogli`` `https://github.com/BhallaLab/moogli/issues`
diff --git a/docs/source/user/py/introduction/release_notes/index.rst b/docs/source/user/py/introduction/release_notes/index.rst
new file mode 100644
index 00000000..862216e9
--- /dev/null
+++ b/docs/source/user/py/introduction/release_notes/index.rst
@@ -0,0 +1,4 @@
+Release Notes
+============
+
+.. todo:: Collect release notes from github.
--
GitLab