more documentation

.gitlab-ci.yml

@@ -16,7 +16,7 @@ check:
 pages:
   stage: deploy
   script:
-  - pip install sphinx sphinxcontrib-blockdiag blockdiag sphinxcontrib-restbuilder numpy sphinx_rtd_theme
+  - pip install sphinx sphinxcontrib-blockdiag blockdiag sphinxcontrib-restbuilder numpy sphinx_rtd_theme m2r
   - python setup.py install
   - sphinx-build -b html -d public/doctrees   doc public
   artifacts:

README.md

-# ESS Beam Physics Python Tools
+## ESS Beam Physics Python Tools
 
 This project provides useful Python tools for executing TraceWin, and reading/writing TraceWin data files.
 
@@ -6,7 +6,7 @@ The files are written primarily for usage at European Spallation Source, but mig
 
 You are free to use this code, but no warranty whatsoever is given.
 
-## Installation
+### Installation
 
 
 To install/ upgrade the package, run the command below. It is assumed that you have git and pip installed on your system.
@@ -19,11 +19,11 @@ If you have installed using Anaconda, we recommend to not use the argument `--us
 
 The argument `-U` implies you should upgrade if you have already installed this package but a newer exist. `--user` implies that this should be installed for the current user only (usually in the folder ~/.local/lib/).
 
-## Usage
+### Usage
 
 Here we will briefly explain how to use the library. Please also see the [Online Documentation](http://ess-bp.pages.esss.lu.se/ess-python-tools).
 
-### lib\_tw
+#### lib\_tw
 
 Some example use cases...
 
@@ -93,7 +93,7 @@ loss_den_from_ptrn=ptrn.loss_den(file_name_dt,dtl_dt=5e-6)
 
 There is another larger example of how you may modify the lattice in the examples folder, see [manipulate_lattice.py](examples/manipulate_lattice/manipulate_lattice.py).
 
-### ess.TraceWin module
+#### ess.TraceWin module
 
 This module was developed in parallell with lib_tw, and contains some overlapping functionality. The module allows you to read (and sometimes write) the various binary files from TraceWin into a pythonized object. Some example usecases follows below.
 For more documentation, also check the built-in help ``help(ess.TraceWin)``
@@ -122,7 +122,7 @@ for f in os.listdir('calc'):
 ```
 
 
-### Error study script
+#### Error study script
 
 First you need to use the GUI to create an error study folder in your output directory (see functionality `Copy set of data`). You may copy as many jobs as you want to run directly in the GUI, but it is very slow and we recommend to rather define the number of runs in the submit command provided here. This submit command use hard links when possible to also save space.
 
@@ -155,13 +155,13 @@ A few things are worth mentioning:
     - For multi-jobs, the templates are *head.multi.tmp* and *queue.multi.tmp*
  - We provide the option to run multi-dynamic study which is perhaps a bit confusing. In this mode, it is assumed that you have already run a number of simulations before. For each new job, we change the seed but read the same error table for dynamical errors. This allows us to understand better if we are limited by static or dynamic tolerances.
 
-#### Example 1
+##### Example 1
 Standard simulation of 100 machines in the folder calc
 ```
 tracewin_errorstudy -n 100 -c calc
 ```
 
-#### Example 2
+##### Example 2
 Simulating 50 machines, then run 20 machines with different static errors but same dynamic errors for each of those (1000 machines total)
 ```
 tracewin_errorstudy -n 50 -c calc

doc/conf.py

@@ -43,6 +43,7 @@ extensions = [
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
     "sphinxcontrib.restbuilder",
+    "m2r",
 ]
 
 # set napoleon style docstring

doc/developer_info.rst

+Developer Information
+---------------------
+
+We largely depend on autodocumentation, which allows the documentation on these pages to be in sync and up to date with
+what is documented in the source.
+
+For documenting the source, we prefer to use the Numpy style as described in napoleon_.
+
+.. _napoleon: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

doc/ess/lib_tw.rst

 ess.lib_tw
 ----------------
 
+.. toctree::
+   :maxdepth: 2
+
 Main description of this module is not written yet
 
+
+API Documentation
+_________________
+
 .. automodule:: ess.lib_tw
     :members:
+
+
+

doc/examples/fieldmap.rst

+fieldmap
+--------
+
+This example shows how fieldmap can be used to modify field map files
+
+.. literalinclude:: ../../examples/fieldmap/fieldmap.py

doc/examples/index.rst

@@ -2,3 +2,8 @@ Examples
 --------
 
 No examples provided yet
+
+.. toctree::
+    
+    lib_tw
+    fieldmap

doc/examples/lib_tw.rst

+Manipulate Lattice
+------------------
+
+This example shows how lib_tw can be used to manipulate the lattice
+
+.. literalinclude:: ../../examples/manipulate_lattice/manipulate_lattice.py

doc/index.rst

@@ -30,9 +30,13 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   readme
+   license
    ess/index
    scripts/index
    examples/index
+   developer_info
+
 
 Indices and tables
 ==================

doc/license.rst

+License
+-------
+
+.. include:: ../LICENSE

doc/readme.rst

+Readme File
+-----------
+
+.. mdinclude:: ../README.md