Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sphinx documentation for python #158

Merged
merged 12 commits into from
Oct 9, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions Doc/sphinx/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
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
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
15 changes: 15 additions & 0 deletions Doc/sphinx/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Sphinx Documentation

The pyMACh3 module is documented using sphinx. Currently you need to build this documentation yourself if you want it (in future this will be automated). To do this, you will need to install Mach3 with its python extension as described above, then go to the [Doc/sphinx](Doc/sphinx) directory. Then you will need to install sphinx and the necessary extensions which can be done using

```
pip install -r requirements.txt
```

then you can simply do

```
make html
```

and the documentation will be built in the build/html directory which you can open with whatever browser you like.
35 changes: 35 additions & 0 deletions Doc/sphinx/make.bat
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)

if "%1" == "" goto help

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
4 changes: 4 additions & 0 deletions Doc/sphinx/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
sphinx
sphinx-rtd-theme
sphinx-automodapi
sphinx-mdinclude
37 changes: 37 additions & 0 deletions Doc/sphinx/source/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'pyMaCh3'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.autosummary",
"sphinx.ext.napoleon",
"sphinx_automodapi.automodapi",
'sphinx_mdinclude'
]

templates_path = ['_templates']
exclude_patterns = []

source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}


# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
22 changes: 22 additions & 0 deletions Doc/sphinx/source/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
.. pyMaCh3 documentation master file, created by
sphinx-quickstart on Tue Oct 8 09:30:39 2024.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to pyMaCh3's documentation!
===================================

.. toctree::
:maxdepth: 4
:caption: Contents:

mainpage
pyMaCh3


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
4 changes: 4 additions & 0 deletions Doc/sphinx/source/mainpage.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Welcome To MaCh3!
=================

.. mdinclude:: ../../mainpage.md
17 changes: 17 additions & 0 deletions Doc/sphinx/source/plotting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
The plotting module can be used to make beautiful plots. See the [plotting wiki page](https://github.com/mach3-software/MaCh3/wiki/15.-Plotting) for information on how to configure the plotting library to work with your MaCh3 output files and other non-MaCh3 based fitters so you can compare results.

The main class to worry about is :py:class:`pyMaCh3.plotting.PlottingManager` which provides the high level functionality and gives you access to everything else you should need. To use this in your plotting script simply do

```
## import the plotting module
from pyMach3 import plotting
## need sys to read command line arguments
import sys

man = plotting.PlottingManager()
## give the command line arguments to the manager
manager.parse_inputs(sys.argv)

## Now plot stuff!!
## ...
```
9 changes: 9 additions & 0 deletions Doc/sphinx/source/plotting.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
plotting
========

.. mdinclude:: plotting.md

.. automodapi:: pyMaCh3.plotting
:members:
:undoc-members:
:show-inheritance:
7 changes: 7 additions & 0 deletions Doc/sphinx/source/pyMaCh3.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
pyMaCh3
=======

.. toctree::
:maxdepth: 4

plotting.rst
6 changes: 2 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,12 +60,10 @@ MaCh3 can be compiled with a python interface by specifying the cmake option
cmake ../ -DMaCh3_PYTHON_ENABLED=ON
make && make install
```
and then adding the path to the installed module to your `PYTHONPATH` environment variable:
```
export PYTHONPATH=$PYTHONPATH:<path>/<to>/<MaCh3>/build/python
```

Currently the python module only contains an interface to the plotting library (see [here](https://github.com/mach3-software/MaCh3/blob/develop/plotting/README.md#python) for more information on how to use it)


### Building with Pip

Additionally you can build just the python module by doing
Expand Down
Loading