Skip to content

Commit 59e42d0

Browse files
domdfcodingdomdfcoding
committed
Added docstrings and sphinx
1 parent d5e648e commit 59e42d0

18 files changed

+562
-127
lines changed

‎.bumpversion.cfg

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,5 @@ tag = True
77

88
[bumpversion:file:domdf_python_tools/__init__.py]
99

10+
[bumpversion:file:doc-source/conf.py]
11+

‎.nojekyll

Whitespace-only changes.

‎README.md

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎README.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
**********************
2+
domdf_python_tools
3+
**********************
4+
5+
Helpful functions for Python
6+
7+

‎build_docs.sh

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#!/usr/bin/env bash
2+
rm -rf docs
3+
cd doc-source
4+
rm -rf build
5+
make html
6+
cp -r build/html ../docs/
7+
cd ../
8+
touch docs/.nojekyll
9+
touch .nojekyll

‎doc-source/Building.rst

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
*********************
2+
Building from source
3+
*********************
4+
5+
To build the domdf_python_tools package from source using ``setuptools``, run the following command:
6+
7+
.. code-block:: bash
8+
9+
$ python3 setup.py sdist bdist_wheel
10+
11+
``setuptools`` is configured using the file :download:`setup.py <../setup.py>`.
12+
13+
14+
Different formats are available for built distributions
15+
16+
.. list-table::
17+
:header-rows: 1
18+
19+
* - Format
20+
- Description
21+
- Notes
22+
* - ``gztar``
23+
- gzipped tar file (``.tar.gz``)
24+
- default on Unix
25+
* - ``bztar``
26+
- bzipped tar file (``.tar.bz2``)
27+
-
28+
* - ``xztar``
29+
- bzipped tar file (``.tar.bz2``)
30+
-
31+
* - ``tar``
32+
- tar file (``.tar``)
33+
-
34+
* - ``zip``
35+
- zip file (``.zip``)
36+
- default on Windows
37+
* - ``wininst``
38+
- self-extracting ZIP file for Windows
39+
-
40+
* - ``msi``
41+
- Microsoft Installer
42+
-
43+
44+
45+
|
46+
47+
**setup.py**
48+
49+
50+
.. literalinclude:: ../../setup.py
51+
:language: python
52+
:linenos:
53+

‎doc-source/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = ReadtheDocsSphinxTheme
8+
SOURCEDIR = .
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc-source/Source.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
*******************************
2+
Downloading source code
3+
*******************************
4+
5+
PyMS source code resides on publicly accessible GitHub servers,
6+
and can be accessed from the following URL: https://github.com/domdfcoding/domdf_python_tools/
7+
8+
If you have ``git`` installed, you can clone the repository with the following command:
9+
10+
.. code-block:: bash
11+
12+
$ git clone https://github.com/domdfcoding/domdf_python_tools/
13+
> Cloning into 'pyms'...
14+
> remote: Enumerating objects: 47, done.
15+
> remote: Counting objects: 100% (47/47), done.
16+
> remote: Compressing objects: 100% (41/41), done.
17+
> remote: Total 173 (delta 16), reused 17 (delta 6), pack-reused 126
18+
> Receiving objects: 100% (173/173), 126.56 KiB | 678.00 KiB/s, done.
19+
> Resolving deltas: 100% (66/66), done.
20+
21+
| Alternatively, the code can be downloaded in a 'zip' file by clicking:
22+
| :guilabel:`Clone or download` --> :guilabel:`Download Zip`
23+
24+
.. figure:: git_download.png
25+
:alt: Downloading a 'zip' file of the source code.
26+
27+
Downloading a 'zip' file of the source code

‎doc-source/conf.py

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
#!/usr/bin/env python3
2+
# -*- coding: utf-8 -*-
3+
4+
import sys
5+
import os
6+
import re
7+
8+
sys.path.append(os.path.abspath('.'))
9+
sys.path.append(os.path.abspath('..'))
10+
sys.path.append(os.path.abspath('./demo/'))
11+
12+
from sphinx.locale import _
13+
14+
15+
project = "domdf_python_tools"
16+
from domdf_python_tools import __author__, __version__, __copyright__
17+
18+
19+
slug = re.sub(r'\W+', '-', project.lower())
20+
version = __version__
21+
release = __version__
22+
author = __author__
23+
copyright = __copyright__
24+
language = 'en'
25+
26+
extensions = [
27+
'sphinx.ext.intersphinx',
28+
'sphinx.ext.autodoc',
29+
'sphinx.ext.mathjax',
30+
'sphinx.ext.viewcode',
31+
'sphinxcontrib.httpdomain',
32+
]
33+
34+
templates_path = ['_templates']
35+
source_suffix = '.rst'
36+
exclude_patterns = []
37+
38+
master_doc = 'index'
39+
suppress_warnings = ['image.nonlocal_uri']
40+
pygments_style = 'default'
41+
42+
intersphinx_mapping = { # Is this where those mystery links are specified?
43+
'rtd': ('https://docs.readthedocs.io/en/latest/', None),
44+
'sphinx': ('http://www.sphinx-doc.org/en/stable/', None),
45+
}
46+
47+
html_theme = 'sphinx_rtd_theme'
48+
html_theme_options = {
49+
'logo_only': False, # True will show just the logo
50+
}
51+
html_theme_path = ["../.."]
52+
#html_logo = "logo/pyms.png"
53+
html_show_sourcelink = False # True will show link to source
54+
55+
html_context = {
56+
# Github Settings
57+
"display_github": True, # Integrate GitHub
58+
"github_user": "domdfcoding", # Username
59+
"github_repo": "domdf_python_tools", # Repo name
60+
"github_version": "master", # Version
61+
"conf_py_path": "/", # Path in the checkout to the docs root
62+
}
63+
64+
htmlhelp_basename = slug
65+
66+
latex_documents = [
67+
('index', '{0}.tex'.format(slug), project, author, 'manual'),
68+
]
69+
70+
man_pages = [
71+
('index', slug, project, [author], 1)
72+
]
73+
74+
texinfo_documents = [
75+
('index', slug, project, author, slug, project, 'Miscellaneous'),
76+
]
77+
78+
79+
# Extensions to theme docs
80+
def setup(app):
81+
from sphinx.domains.python import PyField
82+
from sphinx.util.docfields import Field
83+
84+
app.add_object_type(
85+
'confval',
86+
'confval',
87+
objname='configuration value',
88+
indextemplate='pair: %s; configuration value',
89+
doc_field_types=[
90+
PyField(
91+
'type',
92+
label=_('Type'),
93+
has_arg=False,
94+
names=('type',),
95+
bodyrolename='class'
96+
),
97+
Field(
98+
'default',
99+
label=_('Default'),
100+
has_arg=False,
101+
names=('default',),
102+
),
103+
]
104+
)

‎doc-source/docs.rst

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
**************************
2+
:mod:`domdf_python_tools`
3+
**************************
4+
5+
.. contents:: Table of Contents
6+
7+
.. automodule:: domdf_python_tools
8+
:members:
9+
:private-members:
10+
:special-members:
11+
12+
==================================
13+
:mod:`domdf_python_tools.paths`
14+
==================================
15+
16+
17+
.. automodule:: domdf_python_tools.paths
18+
:members:
19+
:private-members:
20+
:special-members:
21+
22+
===================================
23+
:mod:`domdf_python_tools.terminal`
24+
===================================
25+
26+
27+
.. automodule:: domdf_python_tools.terminal
28+
:members:
29+
:private-members:
30+
:special-members:
31+
32+
==================================
33+
:mod:`domdf_python_tools.utils`
34+
==================================
35+
36+
37+
.. automodule:: domdf_python_tools.utils
38+
:members:
39+
:private-members:
40+
:special-members:
41+
42+

‎doc-source/git_download.png

31.3 KB
Loading

‎doc-source/index.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. include:: ../README.rst
2+
3+
4+
View the :ref:`Function Index <genindex>` or browse the `Source Code <_modules/index.html>`__.
5+
6+
`Browse the GitHub Repository <https://github.com/domdfcoding/domdf_python_tools>`__
7+
8+
.. toctree::
9+
:maxdepth: 3
10+
:caption: Documentation
11+
12+
docs
13+
Source
14+
Building

‎doc-source/make.bat

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=python -msphinx
9+
)
10+
set SPHINXOPTS=
11+
set SPHINXBUILD=sphinx-build
12+
set SOURCEDIR=.
13+
set BUILDDIR=build
14+
set SPHINXPROJ=ReadtheDocsSphinxTheme
15+
16+
if "%1" == "" goto help
17+
18+
%SPHINXBUILD% >NUL 2>NUL
19+
if errorlevel 9009 (
20+
echo.
21+
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
22+
echo.then set the SPHINXBUILD environment variable to point to the full
23+
echo.path of the 'sphinx-build' executable. Alternatively you may add the
24+
echo.Sphinx directory to PATH.
25+
echo.
26+
echo.If you don't have Sphinx installed, grab it from
27+
echo.http://sphinx-doc.org/
28+
exit /b 1
29+
)
30+
31+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
32+
goto end
33+
34+
:help
35+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
36+
37+
:end
38+
popd

‎doc-source/requirements.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
sphinxcontrib-httpdomain
2+
sphinx

0 commit comments

Comments
 (0)