Skip to content
Snippets Groups Projects
Commit ce300ca4 authored by Philip Monaco's avatar Philip Monaco
Browse files

Sphinx documentation setup and pip installation

parent 5059977d
No related branches found
No related tags found
No related merge requests found
Pipeline #1424 passed
# WHY Senior Project
## Installing WHY
There are two way in which the `WHY` package can be installed.
First, follow the [prerequisite](#prerequisites) instructions.
IF you do not need to rebuild documentation or make modifications to the library, follow the instructions under [User Installation](#user-installation).
Otherwise, follow the instructions under [Developer Installation](#developer-installation).
### Prerequisites
The `WHY` requires at least `python3.8` and makes use of a number of third-party libraries. The bare minimum packages are automatically installed when you install `WHY` using `pip`. Additional dependencies for developers are contained in `requirements.txt` file. See the
It's recommended that you use `WHY` within a python virtual environment.
Virtual environments are now included natively with Python 3 using `venv`. Instructions to create a virtual environment can be found [here](https://docs.python.org/3/library/venv.html).
API documentation requires the use of `sphinx` which will require installing `Cmake`. Installation instructions can be found [here](https://cmake.org/install/).
### User Installation
First you must clone the repository using the following bash command.
```bash
pip clone git@gitlab.cci.drexel.edu:pjm363/why-senior-project.git
```
From the root path of the repository (the folder where `setup.py` is located) `WHY` can be installed using `pip` using the following command.
```bash
pip install .
```
### Developer Installation
Developers need an additional tool, `clang-format` in order to run the precommit script.
Install via Ubuntu.
```bash
apt-get install clang-format
```
Install via MacOSX with homebrew.
```bash
brew install clang-format
```
Install via [installer](https://llvm.org/builds/) or using chocolatey via.
```bash
choco install llvm
```
## Building API Documentation
To build the API Documentation in HTML format for local browsing, execute the following from the root of the repository.
```
cd docs/
make html
```
This will also cause any examples contained in `examples` to be generated in the example gallery.
All documentation is also built automatically when the `./precommit.sh` script is run.
# 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)
# 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('../../'))
# -- Project information -----------------------------------------------------
project = 'WHY'
copyright = '2022, Philip Monaco'
author = 'Philip Monaco'
# The full version, including alpha/beta/rc tags
release = '0.1.0'
try:
import re
import WHY
reg = re.compile("([0-9]+\.[0-9]+\.[a-zA-Z0-9\+.]+)")
full_vers = WHY.__version__
partial_vers = reg.mathc(full_vers)[0]
except:
full_vers = "dev"
partial_vers = "dev"
version = partial_vers
release = full_vers
# -- 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",
"sphinx.ext.todo",
"sphinx.ext.napoleon",
"sphinx.ext.autosummary",
"m2r2"
]
autoclass_content = "both"
autosummary_generate = True
source_suffix = [".rst", ".md"]
master_doc = "index"
language = None
pygments_style = "sphinx"
# 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']
# -- 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_rtd_theme'
htmlhelp_basename = "WHYdoc"
html_theme_options = {
"canonical_url":"",
"logo_only": False,
"display_version": True,
"prev_next_buttons_location":"bottom",
"collapse_navigation":True,
"sticky_navigation": True,
"navigation_depth":4,
}
html_logo = ""
man_pages = [(master_doc, "WHY", "WHY Documentation", [author], 1)]
# 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']
todo_include_todos = True
\ No newline at end of file
.. WHY documentation master file, created by
sphinx-quickstart on Mon Feb 14 16:44:55 2022.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to WHY's documentation!
===============================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
## Installing WHY
There are two way in which the `WHY` package can be installed.
First, follow the [prerequisite](#prerequisites) instructions.
IF you do not need to rebuild documentation or make modifications to the library, follow the instructions under [User Installation](#user-installation).
Otherwise, follow the instructions under [Developer Installation](#developer-installation).
### Prerequisites
The `WHY` requires at least `python3.8` and makes use of a number of third-party libraries. The bare minimum packages are automatically installed when you install `WHY` using `pip`. Additional dependencies for developers are contained in `requirements.txt` file. See the
It's recommended that you use `WHY` within a python virtual environment.
Virtual environments are now included natively with Python 3 using `venv`. Instructions to create a virtual environment can be found [here](https://docs.python.org/3/library/venv.html).
API documentation requires the use of `sphinx` which will require installing `Cmake`. Installation instructions can be found [here](https://cmake.org/install/).
### User Installation
First you must clone the repository using the following bash command.
```bash
pip clone git@gitlab.cci.drexel.edu:pjm363/why-senior-project.git
```
From the root path of the repository (the folder where `setup.py` is located) `WHY` can be installed using `pip` using the following command.
```bash
pip install .
```
### Developer Installation
Developers need an additional tool, `clang-format` in order to run the precommit script.
Install via Ubuntu.
```bash
apt-get install clang-format
```
Install via MacOSX with homebrew.
```bash
brew install clang-format
```
Install via [installer](https://llvm.org/builds/) or using chocolatey via.
```bash
choco install llvm
```
## Building API Documentation
To build the API Documentation in HTML format for local browsing, execute the following from the root of the repository.
```
cd docs/
make html
```
This will also cause any examples contained in `examples` to be generated in the example gallery.
All documentation is also built automatically when the `./precommit.sh` script is run.
\ No newline at end of file
import os
import subprocess
from io import open
from setuptools import find_packages, setup
......@@ -25,8 +26,6 @@ core_requires = [
"scikit-learn>=1.0.2"
]
all_requires += core_requires
lint_requires = [
"black==21.12b0",
"isort==5.10.1",
......@@ -34,8 +33,6 @@ lint_requires = [
"mypy"
]
all_requires += lint_requires
docs_requires = [
"Sphinx",
"sphinx-gallery",
......@@ -43,7 +40,17 @@ docs_requires = [
"m2r2"
]
all_requires += docs_requires
all_requires = [
*core_requires,
*lint_requires,
docs_requires,
]
requires_map={
"lint": lint_requires,
"docs": docs_requires,
"all": all_requires,
}
def _minimal_ext_cmd(cmd):
env = {}
......@@ -57,3 +64,57 @@ def _minimal_ext_cmd(cmd):
out = subprocess.check_output(cmd, stderr=subprocess.STDOUT, env=env)
return out
def get_git_hash():
try:
out = _minimal_ext_cmd(["git", "rev-parse", "HEAD"])
git_rev = out.strip().decode("ascii")
except (subprocess.SUbprocessError, OSError):
git_rev = "Unknown"
if not git_rev:
git_rev = "Unknown"
return git_rev
def is_tagged_released():
try:
out = _minimal_ext_cmd(["git", "describe", "--exact-match", "--tags", "HEAD"])
tag_name = out.strip().decode("ascii")
is_tagged_release = tag_name.startswith(SEMVER_STRING)
except (subprocess.SubprocessError, OSError):
is_tagged_release = False
return is_tagged_release
def render_version_string():
version_string = SEMVER_STRING
if os.path.exists(".git") and not is_tagged_released():
version_string += ".dev0+" + get_git_hash()[:7]
return version_string
here = os.path.abspath(os.path.split(__file__)[0])
with open(os.path.join(here, "README.md"), encoding="utf-8") as f:
long_description = f.read()
setup(
name=PROJECT_NAME,
version=render_version_string(),
author=AUTHOR_NAME,
url=PROJECT_URL,
description=PROJECT_DESCRIPTION,
long_description=long_description,
long_description_content_type="text/markdown",
license="LICENSE.md",
packages=find_packages(where="src"),
package_dir={"":"src"},
python_requires=">=3.8",
install_requires=core_requires,
extras_require=requires_map,
include_package_data=True,
zip_safe=False,
package_data={"WHY": ["py.typed"]},
entry_points={},
)
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment