From 60af79691fc5f6dbc778844188f90b8e07b87e50 Mon Sep 17 00:00:00 2001 From: Ross Whitfield Date: Wed, 2 Nov 2016 11:29:49 -0400 Subject: [PATCH] Add start of sphinx docs --- design/planning.md | 20 ------------ docs/Makefile | 55 +++++++++++++++++++++++++++++++ docs/about.rst | 6 ++++ docs/conf.py | 37 +++++++++++++++++++++ docs/index.rst | 12 +++++++ docs/install.rst | 67 ++++++++++++++++++++++++++++++++++++++ docs/javelin.rst | 10 ++++++ docs/javelin/ase.rst | 1 + docs/javelin/fourier.rst | 1 + docs/javelin/grid.rst | 1 + docs/javelin/io.rst | 1 + docs/javelin/structure.rst | 1 + docs/javelin/unitcell.rst | 1 + docs/javelin/utils.rst | 1 + docs/tutorials.rst | 3 ++ javelin/ase.py | 7 +++- javelin/fourier.py | 7 +++- javelin/grid.py | 6 +++- javelin/io.py | 6 ++++ javelin/structure.py | 6 ++++ javelin/unitcell.py | 7 ++++ javelin/utils.py | 6 ++++ 22 files changed, 239 insertions(+), 23 deletions(-) delete mode 100644 design/planning.md create mode 100644 docs/Makefile create mode 100644 docs/about.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/install.rst create mode 100644 docs/javelin.rst create mode 100644 docs/javelin/ase.rst create mode 100644 docs/javelin/fourier.rst create mode 100644 docs/javelin/grid.rst create mode 100644 docs/javelin/io.rst create mode 100644 docs/javelin/structure.rst create mode 100644 docs/javelin/unitcell.rst create mode 100644 docs/javelin/utils.rst create mode 100644 docs/tutorials.rst diff --git a/design/planning.md b/design/planning.md deleted file mode 100644 index fd31955..0000000 --- a/design/planning.md +++ /dev/null @@ -1,20 +0,0 @@ -* Vis of calculated scattering from current DISCUS file. -* Atomic Structure Data Structure (31 JAN 2016) - * Investigation into ASE - includes contact with developers - * check viability of expanding data structure - * Test data structure for large #'s of atoms - * Check viability for Vis, MC, disordered analysis and Fourier transform. -* Develop Fourier Transform method (1 May 2016) -* Scattering data data structure - * Scope metadata - * Initial prototype of data structure (1 Feb 2016) - * Write scattering data to NeXus file to be read into and visualised within Mantid (31 March 2016) -* Test DISCUS file -> FT -> Scattering Data -> Vis (1 July 2016) -* Structure Builder -* ... -* Monte Carlo -* ... -* Disorder Analysis -* ... -* Refinement Loop -* ... diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d561683 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,55 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 0000000..4c2a206 --- /dev/null +++ b/docs/about.rst @@ -0,0 +1,6 @@ +===== +About +===== + +Javelin is a moderisation of DISCUS written in the Python programming +language diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..932531e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,37 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +import os +import sys +sys.path.insert(0, os.path.abspath('..')) + +extensions = [ + 'sphinx.ext.autodoc', +] + +source_suffix = '.rst' + +master_doc = 'index' + +project = 'Javelin' +copyright = '2016, Ross Whitfield' +author = 'Ross Whitfield' + +version = '0.1.0' +release = '0.1.0' + +exclude_patterns = ['_build'] + +pygments_style = 'friendly' + +html_theme = 'nature' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Javelindoc' + +latex_documents = [ + (master_doc, 'Javelin.tex', 'Javelin Documentation', + 'Ross Whitfield', 'manual'), +] + +autodoc_default_flags = ['members', 'undoc-members'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..fe7ff8f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,12 @@ +Javelin +=================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + about + install + tutorials + javelin diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..10f5b8b --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,67 @@ +============ +Installation +============ + +Install the latest release +========================== + +* Update once we have a release + +Requirements +============ + +* Python 2.7-3.5 +* NumPy +* h5py_ +* pandas_ +* xarray_ +* periodictable_ + +Optional: + +* ASE_ (to use the ase atoms structue) + +.. _h5py: +.. _pandas: http://pandas.pydata.org/ +.. _xarray: http://xarray.pydata.org +.. _periodictable: http://www.reflectometry.org/danse/elements.html +.. _ASE: https://wiki.fysik.dtu.dk/ase/ + +Development +=========== + +A development enviroment can easily be set up with either conda of PyPI + +Using Conda +=========== + +.. code:: sh + + conda env create + source activate javelin + python setup.py install + +Using PyPI +========== + +Tests +===== + +The unit tests can be run with pytest_ + +Install with conda +------------------ + +.. code:: sh + + conda install pytest + +Install with PyPI +----------------- + +.. code:: sh + + pip install pytest + +.. _pytest: http://pytest.org + diff --git a/docs/javelin.rst b/docs/javelin.rst new file mode 100644 index 0000000..4b2c348 --- /dev/null +++ b/docs/javelin.rst @@ -0,0 +1,10 @@ +======= +Modules +======= + +List of javelin modules: + +.. toctree:: + :glob: + + javelin/* diff --git a/docs/javelin/ase.rst b/docs/javelin/ase.rst new file mode 100644 index 0000000..cba9a2c --- /dev/null +++ b/docs/javelin/ase.rst @@ -0,0 +1 @@ +.. automodule:: javelin.ase diff --git a/docs/javelin/fourier.rst b/docs/javelin/fourier.rst new file mode 100644 index 0000000..bd6ab28 --- /dev/null +++ b/docs/javelin/fourier.rst @@ -0,0 +1 @@ +.. automodule:: javelin.fourier diff --git a/docs/javelin/grid.rst b/docs/javelin/grid.rst new file mode 100644 index 0000000..5c913ed --- /dev/null +++ b/docs/javelin/grid.rst @@ -0,0 +1 @@ +.. automodule:: javelin.grid diff --git a/docs/javelin/io.rst b/docs/javelin/io.rst new file mode 100644 index 0000000..68af76c --- /dev/null +++ b/docs/javelin/io.rst @@ -0,0 +1 @@ +.. automodule:: javelin.io diff --git a/docs/javelin/structure.rst b/docs/javelin/structure.rst new file mode 100644 index 0000000..8377172 --- /dev/null +++ b/docs/javelin/structure.rst @@ -0,0 +1 @@ +.. automodule:: javelin.structure diff --git a/docs/javelin/unitcell.rst b/docs/javelin/unitcell.rst new file mode 100644 index 0000000..38cf8d1 --- /dev/null +++ b/docs/javelin/unitcell.rst @@ -0,0 +1 @@ +.. automodule:: javelin.unitcell diff --git a/docs/javelin/utils.rst b/docs/javelin/utils.rst new file mode 100644 index 0000000..66c1cbb --- /dev/null +++ b/docs/javelin/utils.rst @@ -0,0 +1 @@ +.. automodule:: javelin.utils diff --git a/docs/tutorials.rst b/docs/tutorials.rst new file mode 100644 index 0000000..e6903aa --- /dev/null +++ b/docs/tutorials.rst @@ -0,0 +1,3 @@ +========= +Tutorials +========= diff --git a/javelin/ase.py b/javelin/ase.py index 0e2cefa..50bc641 100644 --- a/javelin/ase.py +++ b/javelin/ase.py @@ -1,4 +1,9 @@ -"""Theses functions read the legacy DISCUS stru file format in ASE Atoms.""" +""" +ase +=== + +Theses functions read the legacy DISCUS stru file format in ASE Atoms. +""" from __future__ import absolute_import from ase.atoms import Atoms diff --git a/javelin/fourier.py b/javelin/fourier.py index 4367632..72b9261 100644 --- a/javelin/fourier.py +++ b/javelin/fourier.py @@ -1,4 +1,9 @@ -"""This module define the Structure object""" +""" +fourier +======= + +This module define the Structure object +""" import numpy as np import periodictable from javelin.grid import Grid diff --git a/javelin/grid.py b/javelin/grid.py index 9565b19..716d4e6 100644 --- a/javelin/grid.py +++ b/javelin/grid.py @@ -1,4 +1,8 @@ -"""Grid class to allow the Q-space grid to be definied in different +""" +grid +==== + +Grid class to allow the Q-space grid to be definied in different ways Should allow for corners and bins, or a matrix and the axis to be defined. diff --git a/javelin/io.py b/javelin/io.py index dcee96c..07c4558 100644 --- a/javelin/io.py +++ b/javelin/io.py @@ -1,3 +1,9 @@ +""" +io +==== +""" + + def read_mantid_MDHisto(filename): """Read the saved MDHisto from from Mantid and returns an xarray.DataArray object""" import h5py diff --git a/javelin/structure.py b/javelin/structure.py index 67a8dc6..184c6aa 100644 --- a/javelin/structure.py +++ b/javelin/structure.py @@ -1,3 +1,9 @@ +""" +structure +========= +""" + + import numpy as np from pandas import DataFrame from javelin.unitcell import UnitCell diff --git a/javelin/unitcell.py b/javelin/unitcell.py index ca7ad20..6f4e832 100644 --- a/javelin/unitcell.py +++ b/javelin/unitcell.py @@ -1,3 +1,8 @@ +""" +unitcell +======== +""" + import numpy as np @@ -69,6 +74,7 @@ def cartesian(self, u): array([[ 2.59807621e+00, -1.50000000e+00, 3.25954010e-16]]) A array of atoms position can also be passed + >>> positions = [[1,0,0], [0,0,0.5]] >>> unitcell.cartesian(positions) array([[ 2.59807621e+00, -1.50000000e+00, 3.25954010e-16], @@ -124,6 +130,7 @@ def fractional(self, u): array([[ 0.00000000e+00, 1.00000000e+00, -4.89858720e-17]]) A array of atoms position can also be passed + >>> positions = [[0,2,0], [0,0,5]] >>> unitcell.fractional(positions) array([[ 0.00000000e+00, 5.00000000e-01, -2.44929360e-17], diff --git a/javelin/utils.py b/javelin/utils.py index e75c2bc..f30ef36 100644 --- a/javelin/utils.py +++ b/javelin/utils.py @@ -1,3 +1,9 @@ +""" +utils +===== +""" + + def get_atomic_number_symbol(Z=None, symbol=None): import numpy as np from periodictable import elements