From aaf149da245f00d3288af92839f9d88400dd3563 Mon Sep 17 00:00:00 2001 From: Sofiane HADDAD Date: Thu, 10 Nov 2022 12:28:24 +0100 Subject: [PATCH 1/2] Fix autodoc option This closes #2 --- doc/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 970eea1..3edb208 100755 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,7 +40,10 @@ tags.add('nbsphinx') extensions.append('IPython.sphinxext.ipython_console_highlighting') -autodoc_default_flags = ['members', 'inherited-members'] +if LooseVersion(sphinx.__version__) >= LooseVersion('1.8'): + autodoc_default_options = {'members': None, 'inherited-members': None, 'exclude-members': 'thisown'} +else: + autodoc_default_flags = ['members', 'inherited-members'] intersphinx_mapping = {'python': ('http://openturns.github.io/openturns/1.18', 'openturns-objects.inv')} autosummary_generate = True From 5c062c31873f36e1dc7662c07c594ab555500c37 Mon Sep 17 00:00:00 2001 From: Sofiane HADDAD Date: Thu, 10 Nov 2022 15:22:03 +0100 Subject: [PATCH 2/2] Using sphinx gallery - Drop notebook - Using sphinx_gallery - Update example This fixes #1 --- .github/workflows/build.yml | 3 +- doc/conf.py | 74 +++++++++++++++++++------------ doc/examples/README.txt | 0 doc/examples/basic.ipynb | 87 ------------------------------------- doc/examples/examples.rst | 43 ++---------------- doc/examples/plot_basic.py | 31 +++++++++++++ ottemplate/ottemplate.py | 4 +- 7 files changed, 85 insertions(+), 157 deletions(-) create mode 100644 doc/examples/README.txt delete mode 100644 doc/examples/basic.ipynb create mode 100644 doc/examples/plot_basic.py diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 9edf709..a037c71 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -11,7 +11,8 @@ jobs: - name: Build shell: bash -l {0} run: | - conda install -y openturns numpy pytest jupyter numpydoc sphinx nbsphinx jupyter_client ipython pandoc + conda install -y openturns numpy pytest numpydoc sphinx sphinx-gallery pandoc + conda install -c conda-forge sphinx_rtd_theme python setup.py install pytest sudo apt install -y texlive-latex-recommended texlive-fonts-recommended texlive-latex-extra diff --git a/doc/conf.py b/doc/conf.py index 3edb208..8e935c3 100755 --- a/doc/conf.py +++ b/doc/conf.py @@ -14,13 +14,13 @@ import sys, os from distutils.version import LooseVersion import sphinx +import sphinx_gallery import subprocess # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../')) -sys.path.append(os.path.abspath('sphinxext')) # -- General configuration ------------------------------------------------ @@ -31,45 +31,66 @@ 'sphinx.ext.autosummary', 'sphinx.ext.coverage', 'numpydoc', - 'nbsphinx' + 'sphinx_gallery.gen_gallery' ] -nbsphinx_execute = 'never' -# dont add .txt suffix to notebook -html_sourcelink_suffix = '' -tags.add('nbsphinx') -extensions.append('IPython.sphinxext.ipython_console_highlighting') +sphinx_gallery_conf = { + 'examples_dirs': ['examples'], # path to + # example scripts + 'gallery_dirs': ['auto_example'], + 'filename_pattern': '/plot_', + 'run_stale_examples': True, + 'show_signature': False, + # directory where function/class granular galleries are stored + 'backreferences_dir' : 'gen_modules/backreferences', + + # Modules for which function/class level galleries are created. + 'doc_module' : ('openturns'), + + # objects to exclude from implicit backreferences. The default option + # is an empty set, i.e. exclude nothing. + 'exclude_implicit_doc': {}, +} if LooseVersion(sphinx.__version__) >= LooseVersion('1.8'): autodoc_default_options = {'members': None, 'inherited-members': None, 'exclude-members': 'thisown'} else: autodoc_default_flags = ['members', 'inherited-members'] -intersphinx_mapping = {'python': ('http://openturns.github.io/openturns/1.18', 'openturns-objects.inv')} -autosummary_generate = True -numpydoc_show_class_members = True -numpydoc_class_members_toctree = False - -# for equations try: import sphinx.ext.imgmath extensions.append('sphinx.ext.imgmath') + imgmath_latex_preamble = r'\usepackage{{{0}math_notations}}'.format( + os.path.dirname(__file__) + os.sep) imgmath_use_preview = True if subprocess.call('dvisvgm -V', shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE) == 0: imgmath_image_format = 'svg' + # embed image files inside html + imgmath_embed = True except ImportError: extensions.append('sphinx.ext.pngmath') + pngmath_latex_preamble = r'\usepackage{{{0}math_notations}}'.format( + os.path.dirname(__file__) + os.sep) # The next option is used for smart-alignment of math images on the text. # It only works when the preview-latex package is installed. # See http://sphinx-doc.org/latest/ext/math.html#confval-pngmath_use_preview pngmath_use_preview = True +extensions.append('matplotlib.sphinxext.plot_directive') + +intersphinx_mapping = {'python': ( + 'http://openturns.github.io/openturns/1.18', 'openturns-objects.inv')} +autosummary_generate = True + +numpydoc_show_class_members = True +numpydoc_class_members_toctree = False + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. -source_suffix = '.rst' +source_suffix = ['.rst'] # The master toctree document. master_doc = 'index' @@ -98,7 +119,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build','themes', 'sphinxext', '.ipynb_checkpoints'] +exclude_patterns = [] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -129,8 +150,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = 'openturns' -if LooseVersion(sphinx.__version__) < LooseVersion('1.3'): - html_theme = 'default' +html_sourcelink_suffix = '' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -193,23 +213,21 @@ \usepackage{amsfonts} \usepackage{amsmath} \usepackage{expdlist} +\usepackage{math_notations} +\usepackage{stackrel} \let\latexdescription=\description \def\description{\latexdescription{}{} \breaklabel} \DeclareMathOperator*{\argmin}{Argmin} ''' -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -'papersize': 'a4paper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', -# Additional stuff for the LaTeX preamble. -'preamble': latex_preamble, - -# Latex figure (float) alignment -#'figure_align': 'htbp', +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + 'papersize': 'a4paper', + # The font size ('10pt', '11pt' or '12pt'). + 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + 'preamble': latex_preamble, } # Grouping the document tree into LaTeX files. List of tuples diff --git a/doc/examples/README.txt b/doc/examples/README.txt new file mode 100644 index 0000000..e69de29 diff --git a/doc/examples/basic.ipynb b/doc/examples/basic.ipynb deleted file mode 100644 index 98e55fe..0000000 --- a/doc/examples/basic.ipynb +++ /dev/null @@ -1,87 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 1000 - }, - "colab_type": "code", - "id": "YGUS0HXkUUd5", - "outputId": "fc886d15-2464-4b03-a1c2-a8f841e8442e" - }, - "source": [ - "# Notbook using the example" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Module import" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "import ottemplate" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Basic usage" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": { - "colab": {}, - "colab_type": "code", - "id": "nOP6VwgQXd6N" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "9\n" - ] - } - ], - "source": [ - "print(ottemplate.MyClass(3).power(2))" - ] - } - ], - "metadata": { - "colab": { - "name": "using_otconda.ipynb", - "provenance": [] - }, - "kernelspec": { - "display_name": "Python 3", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.9.7" - } - }, - "nbformat": 4, - "nbformat_minor": 0 -} diff --git a/doc/examples/examples.rst b/doc/examples/examples.rst index 7ddd495..0d3d79c 100644 --- a/doc/examples/examples.rst +++ b/doc/examples/examples.rst @@ -1,45 +1,10 @@ Examples ======== -.. toctree:: - :maxdepth: 1 - - basic.ipynb - -Example 1: Axial stressed beam ------------------------------- - -This example is a simple beam, restrained at one side and stressed by a traction load F at the other side. - -1- Problem statement -```````````````````` - -a- Inputs -''''''''' - -- Stochastics variables: +This section illustrates how to use the template. -====== ======================== ================== - Name Description Distribution -====== ======================== ================== -F Traction load Normal(75e3, 5e3) -sigma Axial stress LogNormal(300, 30) -====== ======================== ================== -- Deterministic independent variables: - -======== ================================ ================= -Variable Description Value -======== ================================ ================= -D diameter 20.0 -======== ================================ ================= - -b- Output -''''''''' - -Primary energy savings :math:`G` - -.. math:: - - G = \sigma_e -\frac{F}{\pi \frac{D^2}{4} } +.. toctree:: + + ../auto_example/plot_basic diff --git a/doc/examples/plot_basic.py b/doc/examples/plot_basic.py new file mode 100644 index 0000000..ef9a9b4 --- /dev/null +++ b/doc/examples/plot_basic.py @@ -0,0 +1,31 @@ +""" +Example : Using ottemplatepython module +--------------------------------------- +""" +# %% +# This example aims to illustrate how to use the module. + +# %% +# | Loading python modules + +# %% +import openturns as ot +from openturns.viewer import View +import numpy as np +import ottemplate +from matplotlib import pylab as plt + +# %% +# | Using the module to compute power +print(ottemplate.MyClass(3).power(2)) + +# %% +# | Compute power using arrays +array = np.linspace(-5, 5, 101) +values = ottemplate.MyClass(array).power(2.0) + +# %% +# | Use of graph objects +graph = ot.Graph('Square function', 'x1', 'x2', True, '') +graph.add(ot.Cloud(array, values)) +View(graph).show() diff --git a/ottemplate/ottemplate.py b/ottemplate/ottemplate.py index c7f10e1..7a2d67c 100644 --- a/ottemplate/ottemplate.py +++ b/ottemplate/ottemplate.py @@ -4,7 +4,7 @@ class MyClass(object): """ Class test - Applying power on + Applying power function Parameters ---------- @@ -28,4 +28,4 @@ def power(self, n): y : float The cube value. """ - return np.power(self.value, n) \ No newline at end of file + return np.power(self.value, n)