Documentation Generator (Sphinx Docs) (magpylib#49)

* Add base Sphinx configuration files

* Add __all__ module recognition to public packages

* Fix underline lacking an hyphen in a few files

* Add placeholders for index and custom pages

* Add configuration to show inherited methods in docstrings

* Standardize docstrings - Numpy format ( Issue magpylib#20 )
- Put the correct format for the strings in Sphinx

* Put only relevant pages in the index

* Add Readme to exclude list, remove module pages

* Add placeholder titles for __init__.py in packages

* Adjust levels and add static plages

* Add picture for static pages

* Fix numpy docstrings for moment package (issue magpylib#20)

* Add inherited method notes

* Remove redundant encoding declarations from init

* Add more descriptive docstring to collection

* Add autosummary list to source class init docstring

* Move Readme picture to docs/_static folder

* Add warning and restructure docstrings in collection

* Add sphinx project build and requirement file

* Adjust setup file for Sphinx installation

* Remove relative path from requirements

* Retain private members in docs

* Move autodoc variables up top

* Lock Sphinx Version in conf

* Add Sphinx Version to project's setup.py

* Fix typo in setup variable

* Add Sphinx version to requirements in docs

* Update examples in Collection.py ( magpylib#20 )

* Fix example import

* Update suppression example

* Update RCS method examples (Issue magpylib#20)

* Update current examples ( Issue magpylib#20 )

* Update magnet examples ( Issue magpylib#20 )

* Add epsilon result to magnet example

* Add markdown support to documentation
    - Also add placeholder to index.html

* Add placeholder install instructions in markdown

* Update installation instructions

* Add docs build status badge to readme

* Adjust docs badge

Author: lucasgcb

.gitignore

@@ -72,7 +72,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-
+docs/_autogen/
 # PyBuilder
 target/
 
@@ -122,4 +122,6 @@ dmypy.json
 ### Python Patch ###
 .venv/
 
+
+
 # End of https://www.gitignore.io/api/python

README.md

@@ -1,3 +1,7 @@
+[![](https://readthedocs.com/projects/magpylib-magpylib/badge/?version=sphinx-docs)](https://magpylib-magpylib.readthedocs-hosted.com/)
+
+---
+
 # About
 *A simple and user friendly magnetic toolbox for Python 3.2+*
 
@@ -47,7 +51,7 @@ The library is now in the packCondaTest environment.
 - The total magnetic field that is generated by the collection is calculated on a grid in the xz-plane and is displayed using matplotlib.
 
 **Program output:**
-![](./img/examplePlot.jpg)
+![](./docs/_static/examplePlot.jpg)
 
 **Code:**
 ```python

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@pip install -r ./requirements.txt
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_pages/0_summary.rst

@@ -0,0 +1,22 @@
+MagPyLib Summary
+----------------
+
+The core module of magpylib is :mod:`~magpylib.source`, whose subpackages
+offer the primitive building blocks for creating our simulation data.
+
+The top level serves the :class:`magpylib.Collection`
+class, which offers easy grouping of :mod:`~magpylib.source` objects,
+allowing for the display and combination of fields.
+
+The :mod:`~magpylib.math` module provides on-hand methods for handling axis
+and angle information as well as rotation of position vectors.
+
+.. currentmodule:: magpylib
+
+.. autosummary::
+
+   Collection
+   source
+   math
+
+

docs/_pages/how2install.md

@@ -0,0 +1,31 @@
+# Installation Instructions
+
+
+1. Clone Repo
+    ```
+    git clone https://github.com/ortnermichael/magpylib
+    ```
+2. Enter the Repo
+    ```
+    cd magpylib
+    ```
+3. Install the library into the current environment
+    ```
+    pip install .
+    ```
+
+Generating the documentation:
+1. Clone Repo
+    ```
+    git clone https://github.com/ortnermichael/magpylib
+    ```
+2. Enter the docs Repo
+    ```
+    cd magpylib/docs
+    ```
+3. Run generation with `make`
+    ```
+    make html
+    ```
+
+Documentation is now in `magpylib/docs/_build/html`

docs/_pages/x_examples.rst

@@ -0,0 +1,40 @@
+Examples
+========
+
+The following code executes a mixed simulation with most features.
+
+.. code-block:: python
+
+   # imports
+   import numpy as np
+   import matplotlib.pyplot as plt
+   import magpylib as magpy
+
+   # create magnets
+   magnet1 = magpy.source.magnet.Box(mag=[0,0,600],dim=[3,3,3],pos=[-4,0,3])
+   magnet2 = magpy.source.magnet.Cylinder(mag=[0,0,500], dim=[3,5], pos=[0,0,0])
+
+   # manipulate magnets
+   magnet1.rotate(45,[0,1,0],anchor=[0,0,0])
+   magnet2.move([5,0,-4])
+
+   # collect magnets
+   pmc = magpy.Collection(magnet1,magnet2)
+
+   # display system geometry
+   pmc.displaySystem()
+
+   # calculate B-fields on a grid
+   xs = np.linspace(-10,10,20)
+   zs = np.linspace(-10,10,20)
+   Bs = np.array([[pmc.getB([x,0,z]) for x in xs] for z in zs])
+
+   # display fields using matplotlib
+   fig, ax = plt.subplots()
+   X,Y = np.meshgrid(xs,zs)
+   U,V = Bs[:,:,0], Bs[:,:,2]
+   ax.streamplot(X, Y, U, V, color=np.log(U**2+V**2), density=1.5)
+   plt.show()
+
+
+.. image:: ../_static/examplePlot.jpg

docs/_static/copybutton.js

@@ -0,0 +1,65 @@
+// Copyright 2014 PSF. Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+// File originates from the cpython source found in https://docs.python.org/3/_static/copybutton.js
+
+$(document).ready(function() {
+    /* Add a [>>>] button on the top-right corner of code samples to hide
+     * the >>> and ... prompts and the output and thus make the code
+     * copyable. */
+    var div = $('.highlight-python .highlight,' +
+                '.highlight-default .highlight,' +
+                '.highlight-python3 .highlight')
+    var pre = div.find('pre');
+
+    // get the styles from the current theme
+    pre.parent().parent().css('position', 'relative');
+    var hide_text = 'Hide the prompts and output';
+    var show_text = 'Show the prompts and output';
+    var border_width = pre.css('border-top-width');
+    var border_style = pre.css('border-top-style');
+    var border_color = pre.css('border-top-color');
+    var button_styles = {
+        'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0',
+        'border-color': border_color, 'border-style': border_style,
+        'border-width': border_width, 'color': border_color, 'text-size': '75%',
+        'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em',
+        'border-radius': '0 3px 0 0'
+    }
+
+    // create and add the button to all the code blocks that contain >>>
+    div.each(function(index) {
+        var jthis = $(this);
+        if (jthis.find('.gp').length > 0) {
+            var button = $('<span class="copybutton">Click to Hide &gt;&gt;&gt;</span>');
+            button.css(button_styles)
+            button.attr('title', hide_text);
+            button.data('hidden', 'false');
+            jthis.prepend(button);
+        }
+        // tracebacks (.gt) contain bare text elements that need to be
+        // wrapped in a span to work with .nextUntil() (see later)
+        jthis.find('pre:has(.gt)').contents().filter(function() {
+            return ((this.nodeType == 3) && (this.data.trim().length > 0));
+        }).wrap('<span>');
+    });
+
+    // define the behavior of the button when it's clicked
+    $('.copybutton').click(function(e){
+        e.preventDefault();
+        var button = $(this);
+        if (button.data('hidden') === 'false') {
+            // hide the code output
+            button.parent().find('.go, .gp, .gt').hide();
+            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden');
+            button.css('text-decoration', 'line-through');
+            button.attr('title', show_text);
+            button.data('hidden', 'true');
+        } else {
+            // show the code output
+            button.parent().find('.go, .gp, .gt').show();
+            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible');
+            button.css('text-decoration', 'none');
+            button.attr('title', hide_text);
+            button.data('hidden', 'false');
+        }
+    });
+});