Skip to content

Commit ded7da9

Browse files
johanneskoesterjohanneskoester
committed
docs: separate api docs
1 parent 84ff2b5 commit ded7da9

3 files changed

Lines changed: 352 additions & 3 deletions

File tree

‎docs/conf-api.py‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
#!/usr/bin/env python3
2+
# -*- coding: utf-8 -*-
3+
#
4+
# Snakemake documentation build configuration file, created by
5+
# sphinx-quickstart on Sat Feb 1 16:01:02 2014.
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+
import sys
17+
import os
18+
from datetime import datetime
19+
20+
21+
# If extensions (or modules to document with autodoc) are in another directory,
22+
# add these directories to sys.path here. If the directory is relative to the
23+
# documentation root, use os.path.abspath to make it absolute, like shown here.
24+
sys.path.insert(0, os.path.abspath("../"))
25+
26+
# -- General configuration ------------------------------------------------
27+
28+
# If your documentation needs a minimal Sphinx version, state it here.
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+
extensions = [
35+
"sphinx.ext.autodoc",
36+
"sphinx.ext.mathjax",
37+
"sphinx.ext.viewcode",
38+
"sphinx.ext.napoleon",
39+
"sphinxarg.ext",
40+
"sphinx.ext.autosectionlabel",
41+
"myst_parser",
42+
]
43+
44+
# skip internal class that Sphinx can't process (#296)
45+
autodoc_default_options = {"exclude-members": "lazy_property"}
46+
47+
# Snakemake theme (made by SciAni).
48+
html_css_files = ["theme.css"]
49+
50+
# Add any paths that contain templates here, relative to this directory.
51+
templates_path = ["_templates"]
52+
53+
# The suffix of source filenames.
54+
source_suffix = [".rst", ".md"]
55+
56+
# The encoding of source files.
57+
# source_encoding = 'utf-8-sig'
58+
59+
# The master toctree document.
60+
master_doc = "index-api"
61+
62+
# General information about the project.
63+
project = "Snakemake"
64+
date = datetime.now()
65+
copyright = "2014-{year}, Johannes Koester".format(year=date.timetuple()[0])
66+
67+
import snakemake
68+
69+
# The version info for the project you're documenting, acts as replacement for
70+
# |version| and |release|, also used in various other places throughout the
71+
# built documents.
72+
#
73+
# The short X.Y version.
74+
version = snakemake.__version__
75+
76+
if os.environ.get("READTHEDOCS") == "True":
77+
# Because Read The Docs modifies conf.py, versioneer gives a "dirty"
78+
# version like "5.10.0+0.g28674b1.dirty" that is cleaned here.
79+
version = version.partition("+0.g")[0]
80+
81+
# The full version, including alpha/beta/rc tags.
82+
release = version
83+
84+
# The language for content autogenerated by Sphinx. Refer to documentation
85+
# for a list of supported languages.
86+
# language = None
87+
88+
# There are two options for replacing |today|: either, you set today to some
89+
# non-false value, then it is used:
90+
# today = ''
91+
# Else, today_fmt is used as the format for a strftime call.
92+
# today_fmt = '%B %d, %Y'
93+
94+
# List of patterns, relative to source directory, that match files and
95+
# directories to ignore when looking for source files.
96+
exclude_patterns = ["_build"]
97+
98+
# The reST default role (used for this markup: `text`) to use for all
99+
# documents.
100+
# default_role = None
101+
102+
# If true, '()' will be appended to :func: etc. cross-reference text.
103+
# add_function_parentheses = True
104+
105+
# If true, the current module name will be prepended to all description
106+
# unit titles (such as .. function::).
107+
# add_module_names = True
108+
109+
# If true, sectionauthor and moduleauthor directives will be shown in the
110+
# output. They are ignored by default.
111+
# show_authors = False
112+
113+
# The name of the Pygments (syntax highlighting) style to use.
114+
pygments_style = "sphinx"
115+
116+
# A list of ignored prefixes for module index sorting.
117+
# modindex_common_prefix = []
118+
119+
# If true, keep warnings as "system message" paragraphs in the built documents.
120+
# keep_warnings = False
121+
122+
123+
# -- Options for HTML output ----------------------------------------------
124+
125+
# The theme to use for HTML and HTML Help pages. See the documentation for
126+
# a list of builtin themes.
127+
html_theme = "sphinx_rtd_theme"
128+
129+
# Theme options are theme-specific and customize the look and feel of a theme
130+
# further. For a list of options available for each theme, see the
131+
# documentation.
132+
# html_theme_options = {}
133+
134+
# Add any paths that contain custom themes here, relative to this directory.
135+
# html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
136+
137+
# The name for this set of Sphinx documents. If None, it defaults to
138+
# "<project> v<release> documentation".
139+
# html_title = None
140+
141+
# A shorter title for the navigation bar. Default is the same as html_title.
142+
# html_short_title = None
143+
144+
# The name of an image file (relative to this directory) to place at the top
145+
# of the sidebar.
146+
# html_logo = None
147+
148+
# The name of an image file (within the static path) to use as favicon of the
149+
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
150+
# pixels large.
151+
# html_favicon = None
152+
153+
# Add any paths that contain custom static files (such as style sheets) here,
154+
# relative to this directory. They are copied after the builtin static files,
155+
# so a file named "default.css" will overwrite the builtin "default.css".
156+
html_static_path = ["_static"]
157+
158+
# Add any extra paths that contain custom files (such as robots.txt or
159+
# .htaccess) here, relative to this directory. These files are copied
160+
# directly to the root of the documentation.
161+
# html_extra_path = ["_static/css"]
162+
163+
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
164+
# using the given strftime format.
165+
# html_last_updated_fmt = '%b %d, %Y'
166+
167+
# If true, SmartyPants will be used to convert quotes and dashes to
168+
# typographically correct entities.
169+
# html_use_smartypants = True
170+
171+
# Custom sidebar templates, maps document names to template names.
172+
# html_sidebars = {}
173+
174+
# Additional templates that should be rendered to pages, maps page names to
175+
# template names.
176+
# html_additional_pages = {"index": "index.html"}
177+
178+
# If false, no module index is generated.
179+
# html_domain_indices = True
180+
181+
# If false, no index is generated.
182+
# html_use_index = True
183+
184+
# If true, the index is split into individual pages for each letter.
185+
# html_split_index = False
186+
187+
# If true, links to the reST sources are added to the pages.
188+
# html_show_sourcelink = True
189+
190+
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
191+
# html_show_sphinx = True
192+
193+
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
194+
# html_show_copyright = True
195+
196+
# If true, an OpenSearch description file will be output, and all pages will
197+
# contain a <link> tag referring to it. The value of this option must be the
198+
# base URL from which the finished HTML is served.
199+
# html_use_opensearch = ''
200+
201+
# This is the file name suffix for HTML files (e.g. ".xhtml").
202+
# html_file_suffix = None
203+
204+
# Output file base name for HTML help builder.
205+
htmlhelp_basename = "Snakemakedoc"
206+
207+
208+
# -- Options for LaTeX output ---------------------------------------------
209+
210+
latex_elements = {
211+
# The paper size ('letterpaper' or 'a4paper').
212+
#'papersize': 'letterpaper',
213+
# The font size ('10pt', '11pt' or '12pt').
214+
#'pointsize': '10pt',
215+
# Additional stuff for the LaTeX preamble.
216+
#'preamble': '',
217+
}
218+
219+
# Grouping the document tree into LaTeX files. List of tuples
220+
# (source start file, target name, title,
221+
# author, documentclass [howto, manual, or own class]).
222+
latex_documents = [
223+
("index", "Snakemake.tex", "Snakemake Documentation", "Johannes Koester", "manual"),
224+
]
225+
226+
# The name of an image file (relative to this directory) to place at the top of
227+
# the title page.
228+
# latex_logo = None
229+
230+
# For "manual" documents, if this is true, then toplevel headings are parts,
231+
# not chapters.
232+
# latex_use_parts = False
233+
234+
# If true, show page references after internal links.
235+
# latex_show_pagerefs = False
236+
237+
# If true, show URL addresses after external links.
238+
# latex_show_urls = False
239+
240+
# Documents to append as an appendix to all manuals.
241+
# latex_appendices = []
242+
243+
# If false, no module index is generated.
244+
# latex_domain_indices = True
245+
246+
247+
# -- Options for manual page output ---------------------------------------
248+
249+
# One entry per manual page. List of tuples
250+
# (source start file, name, description, authors, manual section).
251+
man_pages = [("index", "snakemake", "Snakemake Documentation", ["Johannes Koester"], 1)]
252+
253+
# If true, show URL addresses after external links.
254+
# man_show_urls = False
255+
256+
257+
# -- Options for Texinfo output -------------------------------------------
258+
259+
# Grouping the document tree into Texinfo files. List of tuples
260+
# (source start file, target name, title, author,
261+
# dir menu entry, description, category)
262+
texinfo_documents = [
263+
(
264+
"index",
265+
"Snakemake",
266+
"Snakemake Documentation",
267+
"Johannes Koester",
268+
"Snakemake",
269+
"One line description of project.",
270+
"Miscellaneous",
271+
),
272+
]
273+
274+
# Documents to append as an appendix to all manuals.
275+
# texinfo_appendices = []
276+
277+
# If false, no module index is generated.
278+
# texinfo_domain_indices = True
279+
280+
# How to display URL addresses: 'footnote', 'no', or 'inline'.
281+
# texinfo_show_urls = 'footnote'
282+
283+
# If true, do not generate a @detailmenu in the "Top" node's menu.
284+
# texinfo_no_detailmenu = False
285+
286+
287+
def setup(app):
288+
app.add_css_file("sphinx-argparse.css")

‎docs/index-api.rst‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
.. _manual-main:
2+
3+
=========
4+
Snakemake
5+
=========
6+
7+
.. image:: https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod
8+
:target: https://gitpod.io/#https://github.com/snakemake/snakemake
9+
10+
.. image:: https://img.shields.io/conda/dn/bioconda/snakemake.svg?label=Bioconda
11+
:target: https://bioconda.github.io/recipes/snakemake/README.html
12+
13+
.. image:: https://img.shields.io/pypi/pyversions/snakemake.svg
14+
:target: https://www.python.org
15+
16+
.. image:: https://img.shields.io/pypi/v/snakemake.svg
17+
:target: https://pypi.python.org/pypi/snakemake
18+
19+
.. image:: https://img.shields.io/github/workflow/status/snakemake/snakemake/Publish%20to%20Docker%20Hub?color=blue&label=docker%20container&branch=main
20+
:target: https://hub.docker.com/r/snakemake/snakemake
21+
22+
.. image:: https://github.com/snakemake/snakemake/workflows/CI/badge.svg?branch=main&label=tests
23+
:target: https://github.com/snakemake/snakemake/actions?query=branch%3Amain+workflow%3ACI
24+
25+
.. image:: https://img.shields.io/badge/stack-overflow-orange.svg
26+
:target: https://stackoverflow.com/questions/tagged/snakemake
27+
28+
.. image:: https://img.shields.io/twitter/follow/johanneskoester.svg?style=social&label=Follow
29+
:target: https://twitter.com/search?l=&q=%23snakemake%20from%3Ajohanneskoester
30+
31+
.. image:: https://img.shields.io/discord/753690260830945390?label=discord%20chat
32+
:alt: Discord
33+
:target: https://discord.gg/NUdMtmr
34+
35+
.. image:: https://img.shields.io/github/stars/snakemake/snakemake?style=social
36+
:alt: GitHub stars
37+
:target: https://github.com/snakemake/snakemake/stargazers
38+
39+
.. .. raw:: html
40+
<span class="__dimensions_badge_embed__" data-doi="https://doi.org/10.1093/bioinformatics/bts480" data-legend="always" data-style="large_rectangle"></span><script async src="https://badge.dimensions.ai/badge.js" charset="utf-8"></script>
41+
42+
The Snakemake workflow management system is a tool to create **reproducible and scalable** data analyses.
43+
Workflows are described via a human readable, Python based language.
44+
They can be seamlessly scaled to server, cluster, grid and cloud environments, without the need to modify the workflow definition.
45+
Finally, Snakemake workflows can entail a description of required software, which will be automatically deployed to any execution environment.
46+
47+
Snakemake is **highly popular**, with `>7 new citations per week <https://badge.dimensions.ai/details/id/pub.1018944052>`_.
48+
For an introduction, please visit https://snakemake.github.io.
49+
50+
This is the home of the **Snakemake API documentation**, which is meant **purely for developers**.
51+
If you are looking for the Snakemake user documentation, please visit https://snakemake.readthedocs.io.
52+
53+
54+
55+
.. toctree::
56+
:caption: API Reference
57+
:name: api-reference
58+
:hidden:
59+
:maxdepth: 1
60+
61+
api_reference/snakemake
62+
api_reference/snakemake_utils
63+
api_reference/internal/modules

‎docs/index.rst‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Workflows are described via a human readable, Python based language.
4444
They can be seamlessly scaled to server, cluster, grid and cloud environments, without the need to modify the workflow definition.
4545
Finally, Snakemake workflows can entail a description of required software, which will be automatically deployed to any execution environment.
4646

47-
Snakemake is **highly popular**, with `>5 new citations per week <https://badge.dimensions.ai/details/id/pub.1018944052>`_.
47+
Snakemake is **highly popular**, with `>7 new citations per week <https://badge.dimensions.ai/details/id/pub.1018944052>`_.
4848
For an introduction, please visit https://snakemake.github.io.
4949

5050

@@ -160,9 +160,7 @@ Resources
160160
:hidden:
161161
:maxdepth: 1
162162

163-
api_reference/snakemake
164163
api_reference/snakemake_utils
165-
api_reference/internal/modules
166164

167165

168166
.. toctree::

0 commit comments

Comments
 (0)