Skip to content

Commit e66f464

Browse files
rthrth
authored
Add documentation (#1)
1 parent 5728fff commit e66f464

File tree

9 files changed

+369
-0
lines changed

9 files changed

+369
-0
lines changed

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -99,3 +99,5 @@ ENV/
9999

100100
# mypy
101101
.mypy_cache/
102+
_build/
103+
generated/

‎doc/Makefile

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = python -msphinx
7+
SPHINXPROJ = pgeocode
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+
clean:
18+
rm -rf $(BUILDDIR)/*
19+
rm -rf generated/
20+
rm -rf auto_examples/
21+
rm -rf examples/
22+
23+
24+
# Catch-all target: route all unknown targets to Sphinx using the new
25+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
26+
%: Makefile
27+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
28+
29+
30+

‎doc/api.rst

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
API Reference
2+
=============
3+
4+
.. currentmodule:: pgeocode
5+
6+
7+
.. autosummary::
8+
:toctree: ./generated/
9+
10+
pgeocode.Nominatim
11+
pgeocode.GeoDistance
12+
pgeocode.haversine_distance
13+

‎doc/conf.py

+182
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
#!/usr/bin/env python3
2+
# -*- coding: utf-8 -*-
3+
#
4+
# pgeocode documentation build configuration file, created by
5+
# sphinx-quickstart on Sun Feb 4 15:22:38 2018.
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+
sys.path.insert(0, os.path.abspath('sphinxext'))
25+
26+
import pgeocode
27+
28+
from github_link import make_linkcode_resolve
29+
30+
# -- General configuration ------------------------------------------------
31+
32+
# If your documentation needs a minimal Sphinx version, state it here.
33+
#
34+
# needs_sphinx = '1.0'
35+
36+
# Add any Sphinx extension module names here, as strings. They can be
37+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
38+
# ones.
39+
extensions = [
40+
'sphinx.ext.autodoc',
41+
'sphinx.ext.doctest',
42+
'sphinx.ext.mathjax',
43+
'sphinx.ext.autodoc',
44+
'sphinx.ext.autosummary',
45+
'sphinxcontrib.napoleon',
46+
'sphinx.ext.linkcode'
47+
]
48+
49+
50+
autosummary_generate = True
51+
52+
autodoc_default_flags = ['members', 'inherited-members']
53+
54+
# Add any paths that contain templates here, relative to this directory.
55+
templates_path = ['_templates']
56+
57+
# The suffix(es) of source filenames.
58+
# You can specify multiple suffix as a list of string:
59+
#
60+
# source_suffix = ['.rst', '.md']
61+
source_suffix = '.rst'
62+
63+
# The master toctree document.
64+
master_doc = 'index'
65+
66+
# General information about the project.
67+
project = 'pgeocode'
68+
copyright = '2018, Symerio'
69+
author = 'Roman Yurchak'
70+
71+
# The version info for the project you're documenting, acts as replacement for
72+
# |version| and |release|, also used in various other places throughout the
73+
# built documents.
74+
#
75+
# The short X.Y version.
76+
version = pgeocode.__version__
77+
# The full version, including alpha/beta/rc tags.
78+
release = pgeocode.__version__
79+
80+
# The language for content autogenerated by Sphinx. Refer to documentation
81+
# for a list of supported languages.
82+
#
83+
# This is also used if you do content translation via gettext catalogs.
84+
# Usually you set "language" from the command line for these cases.
85+
language = None
86+
87+
# List of patterns, relative to source directory, that match files and
88+
# directories to ignore when looking for source files.
89+
# This patterns also effect to html_static_path and html_extra_path
90+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
91+
92+
# The name of the Pygments (syntax highlighting) style to use.
93+
pygments_style = 'sphinx'
94+
95+
# If true, `todo` and `todoList` produce output, else they produce nothing.
96+
todo_include_todos = False
97+
98+
99+
# -- Options for HTML output ----------------------------------------------
100+
101+
# The theme to use for HTML and HTML Help pages. See the documentation for
102+
# a list of builtin themes.
103+
html_theme = 'sphinx_rtd_theme'
104+
105+
# Theme options are theme-specific and customize the look and feel of a theme
106+
# further. For a list of options available for each theme, see the
107+
# documentation.
108+
#
109+
# html_theme_options = {}
110+
111+
# Add any paths that contain custom static files (such as style sheets) here,
112+
# relative to this directory. They are copied after the builtin static files,
113+
# so a file named "default.css" will overwrite the builtin "default.css".
114+
html_static_path = ['_static']
115+
116+
# Custom sidebar templates, must be a dictionary that maps document names
117+
# to template names.
118+
#
119+
120+
121+
# -- Options for HTMLHelp output ------------------------------------------
122+
123+
# Output file base name for HTML help builder.
124+
htmlhelp_basename = 'pgeocodedoc'
125+
126+
127+
# -- Options for LaTeX output ---------------------------------------------
128+
129+
latex_elements = {
130+
# The paper size ('letterpaper' or 'a4paper').
131+
#
132+
# 'papersize': 'letterpaper',
133+
134+
# The font size ('10pt', '11pt' or '12pt').
135+
#
136+
# 'pointsize': '10pt',
137+
138+
# Additional stuff for the LaTeX preamble.
139+
#
140+
# 'preamble': '',
141+
142+
# Latex figure (float) alignment
143+
#
144+
# 'figure_align': 'htbp',
145+
}
146+
147+
# Grouping the document tree into LaTeX files. List of tuples
148+
# (source start file, target name, title,
149+
# author, documentclass [howto, manual, or own class]).
150+
latex_documents = [
151+
(master_doc, 'pgeocode.tex', 'pgeocode Documentation',
152+
'Roman Yurchak', 'manual'),
153+
]
154+
155+
156+
# -- Options for manual page output ---------------------------------------
157+
158+
# One entry per manual page. List of tuples
159+
# (source start file, name, description, authors, manual section).
160+
man_pages = [
161+
(master_doc, 'pgeocode', 'pgeocode Documentation',
162+
[author], 1)
163+
]
164+
165+
166+
# -- Options for Texinfo output -------------------------------------------
167+
168+
# Grouping the document tree into Texinfo files. List of tuples
169+
# (source start file, target name, title, author,
170+
# dir menu entry, description, category)
171+
texinfo_documents = [
172+
(master_doc, 'pgeocode', 'pgeocode Documentation',
173+
author, 'pgeocode', 'One line description of project.',
174+
'Miscellaneous'),
175+
]
176+
177+
# The following is used by sphinx.ext.linkcode to provide links to github
178+
linkcode_resolve = make_linkcode_resolve('pgeocode',
179+
u'https://github.com/symerio/'
180+
'pgeocode/blob/{revision}/'
181+
'{package}/{path}#L{lineno}')
182+

‎doc/index.rst

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.. pgeocode documentation master file, created by
2+
sphinx-quickstart on Sun Feb 4 15:22:38 2018.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Pgeocode
7+
========
8+
.. toctree::
9+
:maxdepth: 2
10+
:caption: Contents:
11+
12+
overview
13+
api

‎doc/make.bat

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
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 SOURCEDIR=.
11+
set BUILDDIR=_build
12+
set SPHINXPROJ=pgeocode
13+
14+
if "%1" == "" goto help
15+
16+
%SPHINXBUILD% >NUL 2>NUL
17+
if errorlevel 9009 (
18+
echo.
19+
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
20+
echo.then set the SPHINXBUILD environment variable to point to the full
21+
echo.path of the 'sphinx-build' executable. Alternatively you may add the
22+
echo.Sphinx directory to PATH.
23+
echo.
24+
echo.If you don't have Sphinx installed, grab it from
25+
echo.http://sphinx-doc.org/
26+
exit /b 1
27+
)
28+
29+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
30+
goto end
31+
32+
:help
33+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
34+
35+
:end
36+
popd

‎doc/overview.rst

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../README.rst

‎doc/requirements.txt

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
scikit-learn>=0.18
2+
sphinx
3+
pillow
4+
recommonmark
5+
sphinx_rtd_theme
6+
sphinxcontrib-napoleon

‎doc/sphinxext/github_link.py

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Adapted from scikit learn
2+
3+
from operator import attrgetter
4+
import inspect
5+
import subprocess
6+
import os
7+
import sys
8+
from functools import partial
9+
10+
REVISION_CMD = 'git rev-parse --short HEAD'
11+
12+
13+
def _get_git_revision():
14+
try:
15+
revision = subprocess.check_output(REVISION_CMD.split()).strip()
16+
except (subprocess.CalledProcessError, OSError):
17+
print('Failed to execute git to get revision')
18+
return None
19+
return revision.decode('utf-8')
20+
21+
22+
def _linkcode_resolve(domain, info, package, url_fmt, revision):
23+
"""Determine a link to online source for a class/method/function
24+
25+
This is called by sphinx.ext.linkcode
26+
27+
An example with a long-untouched module that everyone has
28+
>>> _linkcode_resolve('py', {'module': 'tty',
29+
... 'fullname': 'setraw'},
30+
... package='tty',
31+
... url_fmt='http://hg.python.org/cpython/file/'
32+
... '{revision}/Lib/{package}/{path}#L{lineno}',
33+
... revision='xxxx')
34+
'http://hg.python.org/cpython/file/xxxx/Lib/tty/tty.py#L18'
35+
"""
36+
37+
if revision is None:
38+
return
39+
if domain not in ('py', 'pyx'):
40+
return
41+
if not info.get('module') or not info.get('fullname'):
42+
return
43+
44+
class_name = info['fullname'].split('.')[0]
45+
if type(class_name) != str:
46+
# Python 2 only
47+
class_name = class_name.encode('utf-8')
48+
module = __import__(info['module'], fromlist=[class_name])
49+
obj = attrgetter(info['fullname'])(module)
50+
51+
try:
52+
fn = inspect.getsourcefile(obj)
53+
except Exception:
54+
fn = None
55+
if not fn:
56+
try:
57+
fn = inspect.getsourcefile(sys.modules[obj.__module__])
58+
except Exception:
59+
fn = None
60+
if not fn:
61+
return
62+
63+
fn = os.path.relpath(fn,
64+
start=os.path.dirname(__import__(package).__file__))
65+
try:
66+
lineno = inspect.getsourcelines(obj)[1]
67+
except Exception:
68+
lineno = ''
69+
return url_fmt.format(revision=revision, package=package,
70+
path=fn, lineno=lineno)
71+
72+
73+
def make_linkcode_resolve(package, url_fmt):
74+
"""Returns a linkcode_resolve function for the given URL format
75+
76+
revision is a git commit reference (hash or name)
77+
78+
package is the name of the root module of the package
79+
80+
url_fmt is along the lines of ('https://github.com/USER/PROJECT/'
81+
'blob/{revision}/{package}/'
82+
'{path}#L{lineno}')
83+
"""
84+
revision = _get_git_revision()
85+
return partial(_linkcode_resolve, revision=revision, package=package,
86+
url_fmt=url_fmt)

0 commit comments

Comments
 (0)