diff --git a/.github/ISSUE_TEMPLATE/01_bugs.md b/.github/ISSUE_TEMPLATE/01_bugs.md new file mode 100644 index 00000000..361aeb4d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01_bugs.md @@ -0,0 +1,14 @@ +--- +name: "\U0001F6A8 Submit a Bug Report" +about: Use this template if you came across a bug or unexpected behaviour differing from the docs. +labels: bug +--- + +## How to reproduce the behaviour + + +## Your Environment + +* textdescriptives Version Used: +* Operating System: +* Python Version Used: \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/02_docs.md b/.github/ISSUE_TEMPLATE/02_docs.md new file mode 100644 index 00000000..01e57c5d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/02_docs.md @@ -0,0 +1,10 @@ +--- +name: "\U0001F4DA Submit a Documentation Report" +about: Did you spot a mistake in the docs, is anything unclear or do you have a + suggestion? +labels: documentation +--- + + +## Which page or section is this issue related to? + diff --git a/.github/ISSUE_TEMPLATE/03_feature-request.md b/.github/ISSUE_TEMPLATE/03_feature-request.md new file mode 100644 index 00000000..6b178788 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/03_feature-request.md @@ -0,0 +1,7 @@ +--- +name: "🚀 Submit a Feature request" +about: Use this template if you want a feature added which is currently not present +labels: enhancement +--- + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..9b4f9307 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: true +contact_links: + - name: 🗯 Discussions forum + url: https://HLasse/textdescriptives/discussions + about: Usage questions, general discussion and anything else that isn't a bug report or a feature request. + - name: 📖 TextDescriptives usage guides & package references + url: https://HLasse.github.io/textdescriptives/ + about: Everything you need to know about textdescriptives and how to use it. + - name: 🛠 Submit a pull request + url: https://github.com/HLasse/textdescriptives/pulls + about: Did you spot a mistake and know how to fix it? Feel free to submit a PR and contribute! diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..27df4cdd --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,29 @@ + +name: Documentation +on: + push: + branches: + - main +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@master + with: + fetch-depth: 0 # otherwise, you will failed to push refs to dest repo + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + pip install sphinx furo sphinx-copybutton sphinxext-opengraph + - name: Build and Commit + uses: sphinx-notes/pages@master + with: + documentation_path: docs + install_requirements: "true" + - name: Push changes + uses: ad-m/github-push-action@master + with: + github_token: ${{ secrets.SPHINX_DOCUMENTATION }} + branch: gh-pages \ No newline at end of file diff --git a/.github/workflows/publish_to_pypi.yml b/.github/workflows/publish_to_pypi.yml new file mode 100644 index 00000000..89b9e5f4 --- /dev/null +++ b/.github/workflows/publish_to_pypi.yml @@ -0,0 +1,35 @@ + +name: Publish to PyPI +on: + push: + branches: [ main ] + +jobs: + pytest: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Set up Python 3.9 + uses: actions/setup-python@v2 + with: + python-version: 3.9 + - name: Install pypa/build + run: >- + python -m + pip install + build + --user + - name: Build a binary wheel and a source tarball + run: >- + python -m + build + --sdist + --wheel + --outdir dist/ + . + - name: Publish distribution 📦 to PyPI + uses: pypa/gh-action-pypi-publish@master + with: + user: __token__ + password: ${{ secrets.PYPI_API_TOKEN }} + skip_existing: true diff --git a/.github/workflows/pytest-cov-comment.yml b/.github/workflows/pytest-cov-comment.yml new file mode 100644 index 00000000..ea5f2d3d --- /dev/null +++ b/.github/workflows/pytest-cov-comment.yml @@ -0,0 +1,47 @@ + +name: CI Pytest +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + pytest: + runs-on: ubuntu-latest + steps: + + - uses: actions/checkout@v2 + - name: Set up Python 3.9 + uses: actions/setup-python@v2 + with: + python-version: 3.9 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install flake8 pytest pytest-cov + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - name: Run and write pytest + run: | + python ./dev/pytest-coverage/run_coverage.py + + - name: Pytest coverage comment + id: coverage-comment + uses: MishaKav/pytest-coverage-comment@v1.0 + with: + pytest-coverage-path: ./dev/pytest-coverage/pytest-coverage.txt + + - name: Check the output coverage + run: | + echo "Coverage Report - ${{ steps.coverage-comment.outputs.coverage }}" + echo "Coverage Color - ${{ steps.coverage-comment.outputs.color }}" + - name: Create the Badge + uses: schneegans/dynamic-badges-action@v1.0.0 + with: + auth: ${{ secrets.PYTEST_COVERAGE_COMMENT }} + gistID: af8637d94475ea8bcb6b6a03c4fbcd3e + filename: badge-dacy-pytest-coverage.json + label: Coverage + message: ${{ steps.coverage-comment.outputs.coverage }} + color: ${{ steps.coverage-comment.outputs.color }} + namedLogo: python diff --git a/.github/workflows/pytest_mac_catalina.yml b/.github/workflows/pytest_mac_catalina.yml new file mode 100644 index 00000000..cc5bf056 --- /dev/null +++ b/.github/workflows/pytest_mac_catalina.yml @@ -0,0 +1,26 @@ +name: Pytest (MacOS Catalina) + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + pytest: + runs-on: macos-10.15 + steps: + + - uses: actions/checkout@v2 + - name: Set up Python 3.9 + uses: actions/setup-python@v2 + with: + python-version: 3.9 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install flake8 pytest pytest-cov + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - name: Run and write pytest + run: | + python ./dev/pytest-coverage/run_coverage.py \ No newline at end of file diff --git a/.github/workflows/pytest_windows.yml b/.github/workflows/pytest_windows.yml new file mode 100644 index 00000000..31289486 --- /dev/null +++ b/.github/workflows/pytest_windows.yml @@ -0,0 +1,28 @@ +# This is a basic workflow to help you get started with Actions + +name: Pytest (Windows) + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + pytest: + runs-on: windows-latest + steps: + + - uses: actions/checkout@v2 + - name: Set up Python 3.9 + uses: actions/setup-python@v2 + with: + python-version: 3.9 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install flake8 pytest pytest-cov + pip install -r requirements.txt + - name: Run and write pytest + run: | + python ./dev/pytest-coverage/run_coverage.py \ No newline at end of file diff --git a/.gitignore b/.gitignore index 75958cf3..ffc1d217 100644 --- a/.gitignore +++ b/.gitignore @@ -27,6 +27,13 @@ share/python-wheels/ *.egg MANIFEST + +# docs +docs/_build/* + +# Mac +.DS_Store +======= # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. @@ -131,4 +138,4 @@ dmypy.json # Mac stuff .DStore -.vscode \ No newline at end of file +.vscode diff --git a/README.md b/README.md index a63706b5..97e23b1e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ - + +[![spacy](https://img.shields.io/badge/built%20with-spaCy-09a3d5.svg)](https://spacy.io) +[![github actions pytest](https://github.com/hlasse/textdescriptives/actions/workflows/pytest-cov-comment.yml/badge.svg)](https://github.com/hlasse/textdescriptives/actions) +[![github actions docs](https://github.com/hlasse/textdescriptives/actions/workflows/documentation.yml/badge.svg)](https://hlasse.io/textdescriptives/) +![github coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/hlasse/GISTID/raw/badge-textdescriptives-pytest-coverage.json) + @@ -113,6 +113,7 @@ The table below shows the metrics included in TextDescriptives and their attribu Developed by Lasse Hansen ([@HLasse](https://lassehansen.me)) at the [Center for Humanities Computing Aarhus](https://chcaa.io) + Collaborators: * Ludvig Renbo Olsen ([@ludvigolsen]( https://github.com/ludvigolsen ), [ludvigolsen.dk]( http://ludvigolsen.dk )) diff --git a/dev/__init__.py b/dev/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/dev/pytest-coverage/.coveragerc b/dev/pytest-coverage/.coveragerc new file mode 100644 index 00000000..55268c2e --- /dev/null +++ b/dev/pytest-coverage/.coveragerc @@ -0,0 +1,3 @@ +[run] +omit = + textdescriptives/tests/* \ No newline at end of file diff --git a/dev/pytest-coverage/run_coverage.py b/dev/pytest-coverage/run_coverage.py new file mode 100644 index 00000000..07fb3521 --- /dev/null +++ b/dev/pytest-coverage/run_coverage.py @@ -0,0 +1,36 @@ +""" +A script for running path +""" +import os +import subprocess +from pathlib import Path + + +import subprocess + +test_failed = False +try: + grepOut = subprocess.check_output( + "pytest --cov=textdescriptives --cov-config=dev/pytest-coverage/.coveragerc --cov-report term-missing", + shell=True, + ) + output = grepOut.decode("utf-8") +except subprocess.CalledProcessError as grepexc: + output = grepexc.output.decode("utf-8") + test_failed = True + print("error code", grepexc.returncode, "\n\n --------- \n", output) + + +save_path = os.path.join("dev", "pytest-coverage") +Path(save_path).mkdir(parents=True, exist_ok=True) + +save_path = os.path.join(save_path, "pytest-coverage.txt") + +if os.path.exists(save_path): + os.remove(save_path) +with open(save_path, "w") as f: + f.write(output) + + +if test_failed is True: + raise ValueError("Tests did not pass") \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -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 = . +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) diff --git a/docs/_static/icon.png b/docs/_static/icon.png new file mode 100644 index 00000000..76b16f80 Binary files /dev/null and b/docs/_static/icon.png differ diff --git a/docs/_static/icon_dark.png b/docs/_static/icon_dark.png new file mode 100644 index 00000000..3ad15e23 Binary files /dev/null and b/docs/_static/icon_dark.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..80f1821c --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,97 @@ +# 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("..")) +sys.path.insert(0, "..") +sys.path.insert(0, os.path.abspath("../")) + + +from textdescriptives.about import __version__ + +# -- Project information ----------------------------------------------------- + +project = "textdescriptives" +author = "Lasse Hansen, Kenneth Enevoldsen" + +# The full version, including alpha/beta/rc tags +release = __version__ + + +# -- 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.napoleon", + "sphinx.ext.viewcode", + "sphinxext.opengraph", + "sphinx_copybutton", + "sphinx.ext.githubpages", +] + +# autodoc_mock_imports = ["textdescriptives"] + +# 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 = "furo" # "press", "sphinx_rtd_theme", "furo" + +# 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"] + +html_show_sourcelink = True + +html_context = { + "display_github": True, # Add 'Edit on Github' link instead of 'View page source' + "github_user": "HLasse", + "github_repo": project, + "github_version": "main", + "conf_py_path": "/docs/", +} + + +html_static_path = ["_static"] + +html_theme_options = { + "light_logo": "icon.png", + "dark_logo": "icon_dark.png", + "light_css_variables": { + "color-brand-primary": "#ff5454", + "color-brand-content": "#ff7575", + }, + "dark_css_variables": { + "color-brand-primary": "#ff8f8f", + "color-brand-content": "#ff8f8f", + }, + "sidebar_hide_name": True, + "navigation_with_keys": True, +} + +# pygments_style = "monokai" +pygments_dark_style = "monokai" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..14ae2465 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,52 @@ +TextDescriptives +================================ + +.. image:: https://img.shields.io/github/stars/hlasse/textdescriptives.svg?style=social&label=Star&maxAge=2592000 + :target: https://github.com/hlasse/textdescriptives + +TextDescriptives is a... add introduction + +📰 News +--------------------------------- + +Add new items + + +Contents +--------------------------------- + +The documentation is organized in three parts: + +- **Getting Started** contains the installation instructions, guides, and tutorials on how to use the package. +- **Package References** contains the documentation of each public class and function. + +.. toctree:: + :maxdepth: 3 + :caption: Getting Started + + installation + usingthepackage + + + +.. toctree:: + :maxdepth: 3 + :caption: Package References + + readability + +.. add more references here + + + +.. toctree:: + GitHub Repository + + + + +Indices and search +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..f8554b43 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,25 @@ +Installation +================== +To get started using TextDescriptives simply install it using pip by running the following line in your terminal: + +.. code-block:: + + pip install textdescriptives + + +Installing from source +^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can also install TextDescriptives directly from source using: + +.. code-block:: + + git clone https://github.com/hlasse/textdescriptives.git + cd TextDescriptives + pip install . + +or + +.. code-block:: + + pip install git+https://github.com/hlasse/textdescriptives diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..2119f510 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%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.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/readability.rst b/docs/readability.rst new file mode 100644 index 00000000..92ff5cfa --- /dev/null +++ b/docs/readability.rst @@ -0,0 +1,13 @@ +Readability +-------------------- + +textdescriptives.readability +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: textdescriptives.readability + :members: + :undoc-members: + :show-inheritance: + +.. :exclude-members: function +.. for functions you wish to exclude \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..d40013d4 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx +furo +sphinx-copybutton +sphinxext-opengraph \ No newline at end of file diff --git a/docs/usingthepackage.rst b/docs/usingthepackage.rst new file mode 100644 index 00000000..e5d7d881 --- /dev/null +++ b/docs/usingthepackage.rst @@ -0,0 +1,13 @@ +Using TextDescriptives +======================= + +Introduction of how to use TD + +.. code-block:: python + + import textdescriptives as td + do_stuff() + + +.. note:: + An example note.