From 0b6caf92fe394bec7f9f43a338dc0e2d3a32d5df Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Thu, 10 Dec 2020 14:17:12 +0530 Subject: [PATCH 1/4] Add RTD docs configuration file Adds a RTD configuration file (v2) to customize builds. Signed-off-by: Ayan Sinha Mahapatra --- .readthedocs.yml | 18 ++++++++++++++++++ setup.cfg | 4 ++++ 2 files changed, 22 insertions(+) create mode 100644 .readthedocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..1b71cd9 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,18 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Where the Sphinx conf.py file is located +sphinx: + configuration: docs/source/conf.py + +# Setting the python version and doc build requirements +python: + install: + - method: pip + path: . + extra_requirements: + - docs diff --git a/setup.cfg b/setup.cfg index a7ab2fe..e4274bb 100644 --- a/setup.cfg +++ b/setup.cfg @@ -35,3 +35,7 @@ testing = # upstream pytest >= 6 pytest-xdist >= 2 +docs= + Sphinx>=3.3.1 + sphinx-rtd-theme>=0.5.0 + doc8>=0.8.1 \ No newline at end of file From f2c1400e39aa99b2a53392910d01509a0a8114f7 Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Thu, 10 Dec 2020 14:19:15 +0530 Subject: [PATCH 2/4] Add basic RTD documentaion #4 Signed-off-by: Ayan Sinha Mahapatra --- docs/Makefile | 20 +++++++++++ docs/make.bat | 35 +++++++++++++++++++ docs/source/conf.py | 63 ++++++++++++++++++++++++++++++++++ docs/source/index.rst | 15 ++++++++ docs/source/skeleton/index.rst | 15 ++++++++ 5 files changed, 148 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/skeleton/index.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /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 = 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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /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=source +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/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..529cae3 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,63 @@ +# 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 = 'nexb-skeleton' +copyright = 'nexb Inc.' +author = 'nexb Inc.' + + +# -- 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 = [ +] + +# 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 = [] + + +# -- 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' + +# 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_context = { + 'css_files': [ + '_static/theme_overrides.css', # override wide tables in RTD theme + ], + "display_github": True, + "github_user": "nexB", + "github_repo": "nexb-skeleton", + "github_version": "develop", # branch + "conf_py_path": "/docs/source/", # path in the checkout to the docs root + } \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..67fcf21 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,15 @@ +Welcome to nexb-skeleton's documentation! +========================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + skeleton/index + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/skeleton/index.rst b/docs/source/skeleton/index.rst new file mode 100644 index 0000000..7dfc6cb --- /dev/null +++ b/docs/source/skeleton/index.rst @@ -0,0 +1,15 @@ +# Docs Structure Guide +# Rst docs - https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +# +# 1. Place docs in folders under source for different sections +# 2. Link them by adding individual index files in each section +# to the main index, and then files for each section to their +# respective index files. +# 3. Use `.. include` statements to include other .rst files +# or part of them, or use hyperlinks to a section of the docs, +# to get rid of repetition. +# https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment +# +# Note: Replace these guide/placeholder docs + +.. include:: ../../../README.rst From e7d19903edae48c176baab11a9a5b7393ae74854 Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Thu, 10 Dec 2020 14:20:49 +0530 Subject: [PATCH 3/4] Add RTD requirements file and test scripts Signed-off-by: Ayan Sinha Mahapatra --- docs/scripts/doc8_style_check.sh | 5 +++++ docs/scripts/sphinx_build_link_check.sh | 5 +++++ 2 files changed, 10 insertions(+) create mode 100644 docs/scripts/doc8_style_check.sh create mode 100644 docs/scripts/sphinx_build_link_check.sh diff --git a/docs/scripts/doc8_style_check.sh b/docs/scripts/doc8_style_check.sh new file mode 100644 index 0000000..9416323 --- /dev/null +++ b/docs/scripts/doc8_style_check.sh @@ -0,0 +1,5 @@ +#!/bin/bash +# halt script on error +set -e +# Check for Style Code Violations +doc8 --max-line-length 100 source --ignore D000 --quiet \ No newline at end of file diff --git a/docs/scripts/sphinx_build_link_check.sh b/docs/scripts/sphinx_build_link_check.sh new file mode 100644 index 0000000..c542686 --- /dev/null +++ b/docs/scripts/sphinx_build_link_check.sh @@ -0,0 +1,5 @@ +#!/bin/bash +# halt script on error +set -e +# Build locally, and then check links +sphinx-build -E -W -b linkcheck source build \ No newline at end of file From 7d37af0b6636ab23780503a0e8de8287ab282b66 Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Wed, 16 Dec 2020 19:45:34 +0530 Subject: [PATCH 4/4] Add `src` folder to pass CI tests and RTD builds Signed-off-by: Ayan Sinha Mahapatra --- src/README.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 src/README.rst diff --git a/src/README.rst b/src/README.rst new file mode 100644 index 0000000..efb1a14 --- /dev/null +++ b/src/README.rst @@ -0,0 +1,5 @@ +Package Module +-------------- + +Put your python modules in this directory. +