Skip to content

Commit b8ad000

Browse files
nils-wernerhameerabbasi
nils-werner
authored and
hameerabbasi
committed
First steps toward documentation (pydata#43)
* First steps toward documentation * Rebase on master and add most docstrings * Fix minor test error after API change. * Switch to sphinx-quickstart and perform copyright changes. * Removing numpydoc because it caused issues. * Removed superfluous Make files * More docstrings * Added more see also's, updated docstrings, moved to autosummary and added intersphinx mappings. * Add lots of examples to docstrings. * Fixed Python 2.7 doctest failure due to different Python2/3 behaviour in Numpy. * Modified template. * Generate separate API pages from docstrings. * Minor TOC changes. * Get rid of some superfluous stuff. * Add internal "See More"s and updated docstrings. * Add autosummary generated docs to bypass missing :imported-members: in Sphinx. * Add random in __all__ and docs/generated. * Document exceptions better and move around docs for COO and __init__. * Fix newline. * Fix newline. (again, damn PyCharm) * Begin building front matter. * Add the basic operations page. * Add lots of docs. * Add indexing and converting to other formats. * Segment and link sparse.COO.rst * Add note to COO about operators and indexing. Add note to indexing about advanced indexing. * Rename "Getting Started" to "User Manual" and add a proper "Getting Started" and "Installing" page. * Fix link warnings.
1 parent d8fc6c8 commit b8ad000

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

75 files changed

+2483
-116
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -58,3 +58,6 @@ docs/_build/
5858

5959
# PyBuilder
6060
target/
61+
62+
# PyCharm
63+
.idea/

‎docs/_templates/autosummary/base.rst

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{{ objname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. auto{{ objtype }}:: {{ objname }}

‎docs/_templates/autosummary/class.rst

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{{ objname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ objname }}
6+
7+
{% block attributes %}
8+
{% if attributes %}
9+
.. rubric:: Attributes
10+
.. autosummary::
11+
:toctree:
12+
{% for item in attributes %}
13+
{{ name }}.{{ item }}
14+
{% endfor %}
15+
{% endif %}
16+
{% endblock %}
17+
18+
{% block methods %}
19+
{% if methods %}
20+
.. rubric:: Methods
21+
.. autosummary::
22+
:toctree:
23+
{% for item in methods %}
24+
{{ name }}.{{ item }}
25+
{% endfor %}
26+
{% endif %}
27+
{% endblock %}

‎docs/_templates/autosummary/module.rst

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{{ fullname | escape | underline }}
2+
3+
.. rubric:: Description
4+
.. automodule:: {{ fullname }}
5+
.. currentmodule:: {{ fullname }}
6+
7+
{% if classes %}
8+
.. rubric:: Classes
9+
.. autosummary::
10+
:toctree:
11+
{% for class in classes %}
12+
{{ class }}
13+
{% endfor %}
14+
{% endif %}
15+
16+
{% if functions %}
17+
.. rubric:: Functions
18+
.. autosummary::
19+
:toctree:
20+
{% for function in functions %}
21+
{{ function }}
22+
{% endfor %}
23+
{% endif %}

‎docs/api.rst

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
API Reference
2+
=============
3+
4+
.. rubric:: Modules
5+
6+
.. autosummary::
7+
:toctree: generated
8+
9+
sparse

‎docs/conf.py

+185
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
#!/usr/bin/env python3
2+
# -*- coding: utf-8 -*-
3+
#
4+
# sparse documentation build configuration file, created by
5+
# sphinx-quickstart on Fri Dec 29 20:58:03 2017.
6+
#
7+
# This file is execfile()d with the current directory set to its
8+
# containing dir.
9+
#
10+
# Note that not all possible configuration values are present in this
11+
# autogenerated file.
12+
#
13+
# All configuration values have a default; values that are commented out
14+
# serve to show the default.
15+
16+
# If extensions (or modules to document with autodoc) are in another directory,
17+
# add these directories to sys.path here. If the directory is relative to the
18+
# documentation root, use os.path.abspath to make it absolute, like shown here.
19+
#
20+
import os
21+
import sys
22+
23+
sys.path.insert(0, os.path.abspath('..'))
24+
25+
# -- General configuration ------------------------------------------------
26+
27+
# If your documentation needs a minimal Sphinx version, state it here.
28+
#
29+
# needs_sphinx = '1.0'
30+
31+
# Add any Sphinx extension module names here, as strings. They can be
32+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
33+
# ones.
34+
35+
extensions = [
36+
'matplotlib.sphinxext.plot_directive',
37+
'sphinx.ext.autodoc',
38+
'sphinx.ext.doctest',
39+
'sphinx.ext.intersphinx',
40+
'sphinx.ext.coverage',
41+
'sphinx.ext.mathjax',
42+
'sphinx.ext.napoleon',
43+
'sphinx.ext.viewcode',
44+
'sphinx.ext.autosummary',
45+
'sphinx.ext.inheritance_diagram',
46+
]
47+
48+
# Add any paths that contain templates here, relative to this directory.
49+
templates_path = ['_templates']
50+
51+
mathjax_path = "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
52+
53+
# The suffix(es) of source filenames.
54+
# You can specify multiple suffix as a list of string:
55+
#
56+
# source_suffix = ['.rst', '.md']
57+
source_suffix = '.rst'
58+
59+
# The master toctree document.
60+
master_doc = 'index'
61+
62+
# General information about the project.
63+
project = 'sparse'
64+
copyright = '2017, Sparse Developers'
65+
author = 'Sparse Developers'
66+
67+
# The version info for the project you're documenting, acts as replacement for
68+
# |version| and |release|, also used in various other places throughout the
69+
# built documents.
70+
#
71+
# The short X.Y version.
72+
version = '0.1.1'
73+
# The full version, including alpha/beta/rc tags.
74+
release = '0.1.1'
75+
76+
# The language for content autogenerated by Sphinx. Refer to documentation
77+
# for a list of supported languages.
78+
#
79+
# This is also used if you do content translation via gettext catalogs.
80+
# Usually you set "language" from the command line for these cases.
81+
language = None
82+
83+
# List of patterns, relative to source directory, that match files and
84+
# directories to ignore when looking for source files.
85+
# This patterns also effect to html_static_path and html_extra_path
86+
exclude_patterns = ['_build', '**tests**', '**setup**', '**extern**',
87+
'**data**']
88+
89+
# The name of the Pygments (syntax highlighting) style to use.
90+
pygments_style = 'sphinx'
91+
92+
# If true, `todo` and `todoList` produce output, else they produce nothing.
93+
todo_include_todos = False
94+
95+
autosummary_generate = True
96+
97+
# -- Options for HTML output ----------------------------------------------
98+
99+
# The theme to use for HTML and HTML Help pages. See the documentation for
100+
# a list of builtin themes.
101+
#
102+
html_theme = "sphinx_rtd_theme"
103+
104+
# Theme options are theme-specific and customize the look and feel of a theme
105+
# further. For a list of options available for each theme, see the
106+
# documentation.
107+
#
108+
# html_theme_options = {}
109+
110+
# Add any paths that contain custom static files (such as style sheets) here,
111+
# relative to this directory. They are copied after the builtin static files,
112+
# so a file named "default.css" will overwrite the builtin "default.css".
113+
# html_static_path = ['_static']
114+
115+
# Custom sidebar templates, must be a dictionary that maps document names
116+
# to template names.
117+
#
118+
# This is required for the alabaster theme
119+
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
120+
# html_sidebars = {
121+
# '**': [
122+
# 'relations.html', # needs 'show_related': True theme option to display
123+
# 'searchbox.html',
124+
# ]
125+
# }
126+
127+
# -- Options for HTMLHelp output ------------------------------------------
128+
129+
# Output file base name for HTML help builder.
130+
htmlhelp_basename = 'sparsedoc'
131+
132+
# -- Options for LaTeX output ---------------------------------------------
133+
134+
latex_elements = {
135+
# The paper size ('letterpaper' or 'a4paper').
136+
#
137+
# 'papersize': 'letterpaper',
138+
139+
# The font size ('10pt', '11pt' or '12pt').
140+
#
141+
# 'pointsize': '10pt',
142+
143+
# Additional stuff for the LaTeX preamble.
144+
#
145+
# 'preamble': '',
146+
147+
# Latex figure (float) alignment
148+
#
149+
# 'figure_align': 'htbp',
150+
}
151+
152+
# Grouping the document tree into LaTeX files. List of tuples
153+
# (source start file, target name, title,
154+
# author, documentclass [howto, manual, or own class]).
155+
latex_documents = [
156+
(master_doc, 'sparse.tex', 'sparse Documentation',
157+
'Sparse Developers', 'manual'),
158+
]
159+
160+
# -- Options for manual page output ---------------------------------------
161+
162+
# One entry per manual page. List of tuples
163+
# (source start file, name, description, authors, manual section).
164+
man_pages = [
165+
(master_doc, 'sparse', 'sparse Documentation',
166+
[author], 1)
167+
]
168+
169+
# -- Options for Texinfo output -------------------------------------------
170+
171+
# Grouping the document tree into Texinfo files. List of tuples
172+
# (source start file, target name, title, author,
173+
# dir menu entry, description, category)
174+
texinfo_documents = [
175+
(master_doc, 'sparse', 'sparse Documentation',
176+
author, 'sparse', 'One line description of project.',
177+
'Miscellaneous'),
178+
]
179+
180+
# Example configuration for intersphinx: refer to the Python standard library.
181+
intersphinx_mapping = {
182+
'python': ('https://docs.python.org/3/', None),
183+
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
184+
'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None)
185+
}

‎docs/contributing.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Contributing to sparse
2+
======================
3+
4+
sparse is a community-driven project on GitHub. You can find our
5+
`repository on GitHub <https://github.com/mrocklin/sparse>`_. Feel
6+
free to open issues for new features or bugs, or open a pull request
7+
to fix a bug or add a new feature.

‎docs/generated/sparse.COO.T.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.T
2+
======
3+
4+
.. currentmodule:: sparse
5+
6+
.. autoattribute:: COO.T

‎docs/generated/sparse.COO.__init__.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.\_\_init\_\_
2+
=================
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.__init__

‎docs/generated/sparse.COO.abs.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.abs
2+
========
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.abs

‎docs/generated/sparse.COO.astype.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.astype
2+
===========
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.astype

‎docs/generated/sparse.COO.broadcast_to.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.broadcast\_to
2+
==================
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.broadcast_to

‎docs/generated/sparse.COO.ceil.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.ceil
2+
=========
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.ceil

‎docs/generated/sparse.COO.conj.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.conj
2+
=========
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.conj

‎docs/generated/sparse.COO.conjugate.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.conjugate
2+
==============
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.conjugate

‎docs/generated/sparse.COO.dot.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.dot
2+
========
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.dot

‎docs/generated/sparse.COO.dtype.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.dtype
2+
==========
3+
4+
.. currentmodule:: sparse
5+
6+
.. autoattribute:: COO.dtype

‎docs/generated/sparse.COO.elemwise.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.elemwise
2+
=============
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.elemwise

‎docs/generated/sparse.COO.enable_caching.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.enable\_caching
2+
====================
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.enable_caching

‎docs/generated/sparse.COO.exp.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.exp
2+
========
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.exp

‎docs/generated/sparse.COO.expm1.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.expm1
2+
==========
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.expm1

‎docs/generated/sparse.COO.floor.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.floor
2+
==========
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.floor

‎docs/generated/sparse.COO.from_numpy.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
COO\.from\_numpy
2+
================
3+
4+
.. currentmodule:: sparse
5+
6+
.. automethod:: COO.from_numpy

0 commit comments

Comments
 (0)