diff --git a/.github/workflows/mkdocs.yaml b/.github/workflows/mkdocs.yaml new file mode 100644 index 000000000..8848782b9 --- /dev/null +++ b/.github/workflows/mkdocs.yaml @@ -0,0 +1,56 @@ +on: [push, pull_request] + +name: Make Sphinx API Docs + +jobs: + mkdocs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Build CPP Core + run: | + git clone https://github.com/symengine/symengine symengine-cpp + cd symengine-cpp + export SOURCE_DIR=`pwd` + git checkout `cat ../symengine_version.txt` + cd $SOURCE_DIR + source bin/install_travis.sh + cd $SOURCE_DIR + bin/test_travis.sh + env: + WITH_MPC: yes + WITH_MPFR: yes + WITH_FLINT: yes + WITH_SCIPY: yes + WITH_DOCS: yes + INTEGER_CLASS: flint + TEST_CPP: no + TEST_SYMPY: yes + MAKEFLAGS: -j2 + our_install_dir: $HOME/our_usr/ + - uses: s-weigand/setup-conda@v1 + - name: Build Bindings and Docs + run: | + export PYTHON_SOURCE_DIR=$GITHUB_WORKSPACE + cd $PYTHON_SOURCE_DIR + source bin/install_travis.sh + bin/test_travis.sh + pip install sphinx-autobuild m2r2 sphinxcontrib-apidoc sphinx-book-theme + sphinx-build docs/ genDocs/ + env: + WITH_MPC: yes + WITH_MPFR: yes + WITH_FLINT: yes + WITH_SCIPY: yes + WITH_DOCS: yes + INTEGER_CLASS: flint + TEST_CPP: no + TEST_SYMPY: yes + MAKEFLAGS: -j2 + our_install_dir: $HOME/our_usr/ + - name: Deploy Documentation + if: ${{ (github.ref == 'refs/heads/main' && github.repository == 'Symengine/symengine.py') || (github.ref == 'refs/heads/master' && github.repository == 'Symengine/symengine.py')}} + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./genDocs diff --git a/.gitignore b/.gitignore index db4d60c66..fb54b321d 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,8 @@ symengine.egg-info/ # Temp files *~ .eggs/ + +# Docs +genDocs/ +docs/_build/ +docs/source/ diff --git a/bin/install_travis.sh b/bin/install_travis.sh index 5b2bdf93f..02d105d54 100644 --- a/bin/install_travis.sh +++ b/bin/install_travis.sh @@ -16,6 +16,10 @@ if [[ "${WITH_SCIPY}" == "yes" ]]; then export conda_pkgs="${conda_pkgs} scipy"; fi +if [[ "${WITH_DOCS}" == "yes" ]]; then + export conda_pkgs="${conda_pkgs} sphinx recommonmark"; +fi + if [[ "${WITH_SAGE}" == "yes" ]]; then # This is split to avoid the 10 minute limit conda install -q sagelib=8.1 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..fd05636c3 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,90 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# 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. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) + +import symengine + +# -- Project information ----------------------------------------------------- + +project = 'symengine' +copyright = '2021, SymEngine development team ' +author = 'SymEngine development team ' + +# The full version, including alpha/beta/rc tags +release = '0.6.1' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", # Consumes docstrings + "sphinx.ext.napoleon", # Allows for Google Style Docs + "sphinx.ext.viewcode", # Links to source code + "sphinx.ext.intersphinx", # Connects to other documentation + "sphinx.ext.todo", # Show TODO details + "sphinx.ext.imgconverter", # Handle svg images + "sphinx.ext.duration", # Shows times in the processing pipeline + "sphinx.ext.mathjax", # Need math support + "sphinx.ext.githubpages", # Puts the .nojekyll and CNAME files + "sphinxcontrib.apidoc", # Automatically sets up sphinx-apidoc + # "recommonmark", # Parses markdown + "m2r2", # Parses markdown in rst +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# API Doc settings +apidoc_module_dir = "../" +apidoc_output_dir = "source" +apidoc_excluded_paths = ["tests"] +apidoc_separate_modules = True + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_book_theme" +html_title = "Symengine Python Bindings" +# html_logo = "path/to/logo.png" +# html_favicon = "path/to/favicon.ico" +html_theme_options = { + "repository_url": "https://github.com/symengine/symengine.py", + "use_repository_button": True, + "use_issues_button": True, + "use_edit_page_button": True, + "path_to_docs": "docs", + "use_download_button": True, + "home_page_in_toc": True +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..9a47bd0a4 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,22 @@ +.. symengine documentation master file, created by + sphinx-quickstart on Tue Jan 26 09:42:30 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Symengine Python API Documentation +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + source/modules + +.. mdinclude:: ../README.md + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`