From e72fcea665c1dd365d9f9317888de8b1e5d99149 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Tue, 26 Jan 2021 15:31:15 +0000 Subject: [PATCH 1/4] docs: Build scripts --- .gitignore | 5 +++ bin/install_travis.sh | 4 ++ docs/conf.py | 90 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 22 +++++++++++ 4 files changed, 121 insertions(+) create mode 100644 docs/conf.py create mode 100644 docs/index.rst 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` From 8ea7f1a10143aa85f54debfdf2e33188a80c4581 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Tue, 2 Feb 2021 06:06:51 +0000 Subject: [PATCH 2/4] gha: Init documentation action --- .github/workflows/mkdocs.yaml | 59 +++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 .github/workflows/mkdocs.yaml diff --git a/.github/workflows/mkdocs.yaml b/.github/workflows/mkdocs.yaml new file mode 100644 index 000000000..18f08952e --- /dev/null +++ b/.github/workflows/mkdocs.yaml @@ -0,0 +1,59 @@ +on: + push: + branches: + - main + - master + +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 + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./genDocs From a1dd147ea0f2c519bfdfbdc7991c482fe2dc1a56 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Tue, 2 Feb 2021 21:00:42 +0000 Subject: [PATCH 3/4] gha: Build always, deploy only for main or master --- .github/workflows/mkdocs.yaml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/mkdocs.yaml b/.github/workflows/mkdocs.yaml index 18f08952e..1d5cec520 100644 --- a/.github/workflows/mkdocs.yaml +++ b/.github/workflows/mkdocs.yaml @@ -1,8 +1,4 @@ -on: - push: - branches: - - main - - master +on: [push, pull_request] name: Make Sphinx API Docs @@ -53,6 +49,7 @@ jobs: MAKEFLAGS: -j2 our_install_dir: $HOME/our_usr/ - name: Deploy Documentation + if: ${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' }} uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} From a6cda095812ef5fc24f62a71192d9e3ce13fc254 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Sun, 14 Feb 2021 17:55:18 +0000 Subject: [PATCH 4/4] gha: Do not attempt deploys from PRs --- .github/workflows/mkdocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/mkdocs.yaml b/.github/workflows/mkdocs.yaml index 1d5cec520..8848782b9 100644 --- a/.github/workflows/mkdocs.yaml +++ b/.github/workflows/mkdocs.yaml @@ -49,7 +49,7 @@ jobs: MAKEFLAGS: -j2 our_install_dir: $HOME/our_usr/ - name: Deploy Documentation - if: ${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' }} + 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 }}