From d24b03faca2ef22d2453304511d438e1874438f8 Mon Sep 17 00:00:00 2001 From: Sakhile Masoka Date: Thu, 22 Oct 2020 11:57:46 +0200 Subject: [PATCH 1/2] Create the docs structure --- docs/Makefile | 4 +- docs/authors.rst | 1 - docs/conf.py | 271 ++++---------------- docs/contributing.rst | 1 - docs/docs/Makefile | 20 -- docs/docs/authors.rst | 1 - docs/docs/conf.py | 310 ----------------------- docs/docs/contributing.rst | 1 - docs/docs/history.rst | 1 - docs/docs/index.rst | 20 -- docs/docs/installation.rst | 51 ---- docs/docs/make.bat | 36 --- docs/docs/readme.rst | 1 - docs/docs/usage.rst | 7 - docs/history.rst | 1 - docs/index.rst | 18 +- docs/installation.rst | 51 ---- docs/make.bat | 36 --- docs/modules.rst | 7 + docs/readme.rst | 1 - docs/tricolour.apps.rst | 10 + docs/tricolour.apps.tricolour.rst | 30 +++ docs/tricolour.rst | 86 +++++++ docs/usage.rst | 55 ---- requirements_dev.txt => requirements.txt | 0 25 files changed, 198 insertions(+), 822 deletions(-) delete mode 100644 docs/authors.rst mode change 100755 => 100644 docs/conf.py delete mode 100644 docs/contributing.rst delete mode 100644 docs/docs/Makefile delete mode 100644 docs/docs/authors.rst delete mode 100755 docs/docs/conf.py delete mode 100644 docs/docs/contributing.rst delete mode 100644 docs/docs/history.rst delete mode 100644 docs/docs/index.rst delete mode 100644 docs/docs/installation.rst delete mode 100644 docs/docs/make.bat delete mode 100644 docs/docs/readme.rst delete mode 100644 docs/docs/usage.rst delete mode 100644 docs/history.rst delete mode 100644 docs/installation.rst delete mode 100644 docs/make.bat create mode 100644 docs/modules.rst delete mode 100644 docs/readme.rst create mode 100644 docs/tricolour.apps.rst create mode 100644 docs/tricolour.apps.tricolour.rst create mode 100644 docs/tricolour.rst delete mode 100644 docs/usage.rst rename requirements_dev.txt => requirements.txt (100%) diff --git a/docs/Makefile b/docs/Makefile index 3f7cad3..6c28a08 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = python -msphinx +SPHINXBUILD = sphinx-build SPHINXPROJ = tricolour SOURCEDIR = . BUILDDIR = _build @@ -17,4 +17,4 @@ help: # 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) + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/authors.rst b/docs/authors.rst deleted file mode 100644 index e122f91..0000000 --- a/docs/authors.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../AUTHORS.rst diff --git a/docs/conf.py b/docs/conf.py old mode 100755 new mode 100644 index 4fa4775..f5f08c1 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,66 +1,45 @@ -#!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# cookiecutter-pypackage documentation build configuration file, created by -# sphinx-quickstart on Sun Dec 13 09:13:01 2015. +# Configuration file for the Sphinx documentation builder. # -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sphinx_rtd_theme -import sys -import os -import shlex +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/stable/config -sys.path.insert(0, os.path.abspath("..")) - -import tricolour +# -- 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. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# +import os +import sys +sys.path.insert(0, os.path.abspath('../tricolour/')) -try: - from unittest.mock import MagicMock -except ImportError: - from mock import Mock as MagicMock +# -- Project information ----------------------------------------------------- -class Mock(MagicMock): - @classmethod - def __getattr__(cls, name): - obj = MagicMock() - obj.__name__ = "name" - obj.__doc__ = "doc" - return obj +project = 'tricolour' +copyright = '2019, SARAO' +author = 'Simon Perkins, Ben Hugo' +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '0.1.5' -MOCK_MODULES = ['numpy', 'numba', 'dask'] -sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES) +# -- General configuration --------------------------------------------------- +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx.ext.extlinks', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', 'sphinx.ext.viewcode', ] @@ -69,29 +48,13 @@ def __getattr__(cls, name): # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: +# # source_suffix = ['.rst', '.md'] source_suffix = '.rst' -# The encoding of source files. -#source_encoding = 'utf-8-sig' - # The master toctree document. master_doc = 'index' -# General information about the project. -project = 'tricolour' -copyright = '2019, SARAO' -author = 'Simon Perkins' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = tricolour.__version__ -# The full version, including alpha/beta/rc tags. -release = tricolour.__version__ - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -99,155 +62,67 @@ def __getattr__(cls, name): # Usually you set "language" from the command line for these cases. language = None -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - - -# -- Options for HTML output ---------------------------------------------- +# -- 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' +# +html_theme = 'sphinx-rtd-theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None +# +# html_theme_options = {} # 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'] -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' +# -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = 'cookiecutter-pypackagedoc' +htmlhelp_basename = 'tricolourdoc' + -# -- Options for LaTeX output --------------------------------------------- +# -- Options for LaTeX output ------------------------------------------------ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). + # # 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). + # # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. + # # 'preamble': '', # Latex figure (float) alignment + # # 'figure_align': 'htbp', } @@ -255,69 +130,31 @@ def __getattr__(cls, name): # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'cookiecutter-pypackage.tex', 'cookiecutter-pypackage Documentation', - 'Audrey Roy Greenfeld', 'manual'), + (master_doc, 'tricolour.tex', 'tricolour Documentation', + 'Simon Perkins, Ben Hugo', 'manual'), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- +# -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'cookiecutter-pypackage', 'cookiecutter-pypackage Documentation', + (master_doc, 'tricolour', 'tricolour Documentation', [author], 1) ] -# If true, show URL addresses after external links. -#man_show_urls = False - -# -- Options for Texinfo output ------------------------------------------- +# -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'cookiecutter-pypackage', 'cookiecutter-pypackage Documentation', - author, 'cookiecutter-pypackage', 'One line description of project.', + (master_doc, 'tricolour', 'tricolour Documentation', + author, 'tricolour', 'One line description of project.', 'Miscellaneous'), ] -extlinks = { - 'issue': ('https://github.com/ska-sa/tricolour/issues/%s', 'GH#'), - 'pr': ('https://github.com/ska-sa/tricolour/pull/%s', 'GH#') -} - - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False +# -- Extension configuration ------------------------------------------------- \ No newline at end of file diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index e582053..0000000 --- a/docs/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../CONTRIBUTING.rst diff --git a/docs/docs/Makefile b/docs/docs/Makefile deleted file mode 100644 index 3f7cad3..0000000 --- a/docs/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = python -msphinx -SPHINXPROJ = tricolour -SOURCEDIR = . -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/docs/authors.rst b/docs/docs/authors.rst deleted file mode 100644 index e122f91..0000000 --- a/docs/docs/authors.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../AUTHORS.rst diff --git a/docs/docs/conf.py b/docs/docs/conf.py deleted file mode 100755 index d79a0d1..0000000 --- a/docs/docs/conf.py +++ /dev/null @@ -1,310 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# -# cookiecutter-pypackage documentation build configuration file, created by -# sphinx-quickstart on Sun Dec 13 09:13:01 2015. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys -import os -import shlex - -# 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. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -try: - from unittest.mock import MagicMock -except ImportError: - from mock import Mock as MagicMock - -class Mock(MagicMock): - @classmethod - def __getattr__(cls, name): - obj = MagicMock() - obj.__name__ = "name" - obj.__doc__ = "doc" - return obj - -MOCK_MODULES = [] - -sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES) - -import sphinx_rtd_theme - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.viewcode', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = 'cookiecutter-pypackage' -copyright = '2015, Audrey Roy Greenfeld' -author = 'Audrey Roy Greenfeld' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.9.0' -# The full version, including alpha/beta/rc tags. -release = '0.9.0' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - - -# -- 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' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# 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'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'cookiecutter-pypackagedoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', - -# Latex figure (float) alignment -#'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'cookiecutter-pypackage.tex', 'cookiecutter-pypackage Documentation', - 'Audrey Roy Greenfeld', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'cookiecutter-pypackage', 'cookiecutter-pypackage Documentation', - [author], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'cookiecutter-pypackage', 'cookiecutter-pypackage Documentation', - author, 'cookiecutter-pypackage', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False diff --git a/docs/docs/contributing.rst b/docs/docs/contributing.rst deleted file mode 100644 index e582053..0000000 --- a/docs/docs/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../CONTRIBUTING.rst diff --git a/docs/docs/history.rst b/docs/docs/history.rst deleted file mode 100644 index 2506499..0000000 --- a/docs/docs/history.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../HISTORY.rst diff --git a/docs/docs/index.rst b/docs/docs/index.rst deleted file mode 100644 index 217d726..0000000 --- a/docs/docs/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -Welcome to tricolour's documentation! -====================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - readme - installation - usage - modules - contributing - authors - history - -Indices and tables -================== -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/docs/installation.rst b/docs/docs/installation.rst deleted file mode 100644 index 1ea4758..0000000 --- a/docs/docs/installation.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. highlight:: shell - -============ -Installation -============ - - -Stable release --------------- - -To install tricolour, run this command in your terminal: - -.. code-block:: console - - $ pip install tricolour - -This is the preferred method to install tricolour, as it will always install the most recent stable release. - -If you don't have `pip`_ installed, this `Python installation guide`_ can guide -you through the process. - -.. _pip: https://pip.pypa.io -.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/ - - -From sources ------------- - -The sources for tricolour can be downloaded from the `Github repo`_. - -You can either clone the public repository: - -.. code-block:: console - - $ git clone git://github.com/ska-sa/tricolour - -Or download the `tarball`_: - -.. code-block:: console - - $ curl -OL https://github.com/ska-sa/tricolour/tarball/master - -Once you have a copy of the source, you can install it with: - -.. code-block:: console - - $ python setup.py install - - -.. _Github repo: https://github.com/ska-sa/tricolour -.. _tarball: https://github.com/ska-sa/tricolour/tarball/master diff --git a/docs/docs/make.bat b/docs/docs/make.bat deleted file mode 100644 index a7c821f..0000000 --- a/docs/docs/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=python -msphinx -) -set SOURCEDIR=. -set BUILDDIR=_build -set SPHINXPROJ=tricolour - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The Sphinx module was not found. Make sure you have Sphinx installed, - echo.then set the SPHINXBUILD environment variable to point to the full - echo.path of the 'sphinx-build' executable. Alternatively you may add the - echo.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% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd diff --git a/docs/docs/readme.rst b/docs/docs/readme.rst deleted file mode 100644 index 72a3355..0000000 --- a/docs/docs/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../README.rst diff --git a/docs/docs/usage.rst b/docs/docs/usage.rst deleted file mode 100644 index a42cd7a..0000000 --- a/docs/docs/usage.rst +++ /dev/null @@ -1,7 +0,0 @@ -===== -Usage -===== - -To use tricolour in a project:: - - import tricolour diff --git a/docs/history.rst b/docs/history.rst deleted file mode 100644 index 2506499..0000000 --- a/docs/history.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../HISTORY.rst diff --git a/docs/index.rst b/docs/index.rst index eb9b23c..c36058d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,20 +1,20 @@ -Welcome to Tricolour's documentation! -====================================== +.. tricolour documentation master file, created by + sphinx-quickstart on Thu Oct 22 11:04:33 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to tricolour's documentation! +===================================== .. toctree:: :maxdepth: 2 :caption: Contents: - readme - installation - usage - modules - contributing - authors - history + Indices and tables ================== + * :ref:`genindex` * :ref:`modindex` * :ref:`search` diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index 7a1c316..0000000 --- a/docs/installation.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. highlight:: shell - -============ -Installation -============ - - -Stable release --------------- - -To install Tricolour, run this command in your terminal: - -.. code-block:: console - - $ pip install tricolour - -This is the preferred method to install Tricolour, as it will always install the most recent stable release. - -If you don't have `pip`_ installed, this `Python installation guide`_ can guide -you through the process. - -.. _pip: https://pip.pypa.io -.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/ - - -From sources ------------- - -The sources for Tricolour can be downloaded from the `Github repo`_. - -You can either clone the public repository: - -.. code-block:: console - - $ git clone git://github.com/ska-sa/tricolour - -Or download the `tarball`_: - -.. code-block:: console - - $ curl -OL https://github.com/ska-sa/tricolour/tarball/master - -Once you have a copy of the source, you can install it with: - -.. code-block:: console - - $ python setup.py install - - -.. _Github repo: https://github.com/ska-sa/tricolour -.. _tarball: https://github.com/ska-sa/tricolour/tarball/master diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index a7c821f..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=python -msphinx -) -set SOURCEDIR=. -set BUILDDIR=_build -set SPHINXPROJ=tricolour - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The Sphinx module was not found. Make sure you have Sphinx installed, - echo.then set the SPHINXBUILD environment variable to point to the full - echo.path of the 'sphinx-build' executable. Alternatively you may add the - echo.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% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000..30c4103 --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,7 @@ +tricolour +========= + +.. toctree:: + :maxdepth: 4 + + tricolour diff --git a/docs/readme.rst b/docs/readme.rst deleted file mode 100644 index 72a3355..0000000 --- a/docs/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../README.rst diff --git a/docs/tricolour.apps.rst b/docs/tricolour.apps.rst new file mode 100644 index 0000000..bf0b25b --- /dev/null +++ b/docs/tricolour.apps.rst @@ -0,0 +1,10 @@ +tricolour.apps package +====================== + +Module contents +--------------- + +.. automodule:: tricolour.apps + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/tricolour.apps.tricolour.rst b/docs/tricolour.apps.tricolour.rst new file mode 100644 index 0000000..ddb9ec8 --- /dev/null +++ b/docs/tricolour.apps.tricolour.rst @@ -0,0 +1,30 @@ +tricolour.apps.tricolour package +================================ + +Submodules +---------- + +tricolour.apps.tricolour.app module +----------------------------------- + +.. automodule:: tricolour.apps.tricolour.app + :members: + :undoc-members: + :show-inheritance: + +tricolour.apps.tricolour.strat\_executor module +----------------------------------------------- + +.. automodule:: tricolour.apps.tricolour.strat_executor + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: tricolour.apps.tricolour + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/tricolour.rst b/docs/tricolour.rst new file mode 100644 index 0000000..c72d396 --- /dev/null +++ b/docs/tricolour.rst @@ -0,0 +1,86 @@ +tricolour package +================= + +Submodules +---------- + +tricolour.banner module +----------------------- + +.. automodule:: tricolour.banner + :members: + :undoc-members: + :show-inheritance: + +tricolour.dask\_wrappers module +------------------------------- + +.. automodule:: tricolour.dask_wrappers + :members: + :undoc-members: + :show-inheritance: + +tricolour.flagging module +------------------------- + +.. automodule:: tricolour.flagging + :members: + :undoc-members: + :show-inheritance: + +tricolour.mask module +--------------------- + +.. automodule:: tricolour.mask + :members: + :undoc-members: + :show-inheritance: + +tricolour.packing module +------------------------ + +.. automodule:: tricolour.packing + :members: + :undoc-members: + :show-inheritance: + +tricolour.post\_mortem\_handler module +-------------------------------------- + +.. automodule:: tricolour.post_mortem_handler + :members: + :undoc-members: + :show-inheritance: + +tricolour.stokes module +----------------------- + +.. automodule:: tricolour.stokes + :members: + :undoc-members: + :show-inheritance: + +tricolour.util module +--------------------- + +.. automodule:: tricolour.util + :members: + :undoc-members: + :show-inheritance: + +tricolour.window\_statistics module +----------------------------------- + +.. automodule:: tricolour.window_statistics + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: tricolour + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index 6f16e36..0000000 --- a/docs/usage.rst +++ /dev/null @@ -1,55 +0,0 @@ -===== -Usage -===== - -Command Line ------------- - -The flagger can be run from the command line:: - - $ tricolour --help - usage: tricolour [-h] [-c CONFIG] [-if] [-fs {standard,polarisation}] - [-rc ROW_CHUNKS] [-nw NWORKERS] - ms - - positional arguments: - ms Measurement Set - - optional arguments: - -h, --help show this help message and exit - -c CONFIG, --config CONFIG - YAML config file containing parameters for the flagger - in the 'sum_threshold' key. (default: ) - -if, --ignore-flags - -fs {standard,polarisation}, --flagging-strategy {standard,polarisation} - Flagging Strategy. If 'standard' all correlations in - the visibility are flagged independently. If - 'polarisation' the polarised intensity sqrt(Q^2 + U^2 - + V^2) is calculated and used to flag all correlations - in the visibility. (default: standard) - -rc ROW_CHUNKS, --row-chunks ROW_CHUNKS - Hint indicating the number of Measurement Set rows to - read in a single chunk. Smaller and larger numbers - will tend to respectively decrease or increase both - memory usage and computational efficiency (default: - 10000) - -nw NWORKERS, --nworkers NWORKERS - Number of workers (threads) to use. By default, set to - twice the number of logical CPUs on the system. Many - workers can also affect memory usage on systems with - many cores. (default: 16) - -Sample Configuration Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A sample configuration file is shown in ``conf/default.yml``: - -.. literalinclude:: ../conf/default.yaml - :language: yaml - -Within a Project ----------------- - -To use Tricolour in a project:: - - import tricolour diff --git a/requirements_dev.txt b/requirements.txt similarity index 100% rename from requirements_dev.txt rename to requirements.txt From 3d6adfe8c9a05fbe13999a505c56f5368bc5eeff Mon Sep 17 00:00:00 2001 From: Sakhile Masoka Date: Mon, 26 Oct 2020 17:18:38 +0200 Subject: [PATCH 2/2] Added structure for the docs --- README.rst | 20 ++++++++++++++++ docs/authors.rst | 1 + docs/conf.py | 8 ++++++- docs/contributing.rst | 1 + docs/examples.rst | 5 ++++ docs/history.rst | 1 + docs/index.rst | 15 +++++++----- docs/installation.rst | 53 +++++++++++++++++++++++++++++++++++++++++++ docs/modules.rst | 2 +- docs/readme.rst | 1 + docs/usage.rst | 13 +++++++++++ 11 files changed, 112 insertions(+), 8 deletions(-) create mode 100644 docs/authors.rst create mode 100644 docs/contributing.rst create mode 100644 docs/examples.rst create mode 100644 docs/history.rst create mode 100644 docs/installation.rst create mode 100644 docs/readme.rst create mode 100644 docs/usage.rst diff --git a/README.rst b/README.rst index 4adde3b..6254142 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,26 @@ ========= Tricolour ========= +.. image:: https://img.shields.io/pypi/v/tricolour.svg + :target: https://pypi.python.org/pypi/tricolour + +.. image:: https://img.shields.io/travis/ska-sa/tricolour.svg + :target: https://travis-ci.org/ska-sa/tricolour + +.. image:: https://readthedocs.org/projects/tricolour/badge/?version=latest + :target: https://tricolour.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + + +.. image:: https://pyup.io/repos/github/ska-sa/tricolour/shield.svg + :target: https://pyup.io/repos/github/ska-sa/tricolour/ + :alt: Updates + A variant of the Science Data Processing flagging code, wrapped in dask, operating on Measurement Sets. + +Documentation +------------- + +https://tricolour.readthedocs.io. \ No newline at end of file diff --git a/docs/authors.rst b/docs/authors.rst new file mode 100644 index 0000000..94292d0 --- /dev/null +++ b/docs/authors.rst @@ -0,0 +1 @@ +.. include:: ../AUTHORS.rst \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index f5f08c1..c9127e6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,6 +14,7 @@ # import os import sys +import sphinx_rtd_theme sys.path.insert(0, os.path.abspath('../tricolour/')) @@ -40,7 +41,12 @@ # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', 'sphinx.ext.viewcode', + 'sphinx.ext.mathjax', + 'sphinx.ext.githubpages', + 'numpydoc', + 'sphinx_rtd_theme', ] # Add any paths that contain templates here, relative to this directory. @@ -76,7 +82,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx-rtd-theme' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..3bdd7dc --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst \ No newline at end of file diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..0540a69 --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,5 @@ +================== +Example Strategies +================== + +Example Strategies \ No newline at end of file diff --git a/docs/history.rst b/docs/history.rst new file mode 100644 index 0000000..bec23d8 --- /dev/null +++ b/docs/history.rst @@ -0,0 +1 @@ +.. include:: ../HISTORY.rst \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index c36058d..120d2b5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,4 @@ -.. tricolour documentation master file, created by - sphinx-quickstart on Thu Oct 22 11:04:33 2020. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - +===================================== Welcome to tricolour's documentation! ===================================== @@ -10,7 +6,14 @@ Welcome to tricolour's documentation! :maxdepth: 2 :caption: Contents: - + readme + installation + usage + modules + examples + contributing + authors + history Indices and tables ================== diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..d25bab0 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,53 @@ +.. highlight:: shell + +============ +Installation +============ + + +Stable release +-------------- + +To install Triclour, run this command in your terminal: + +.. code-block:: console + + $ pip install triclour + +This is the preferred method to install Triclour, +as it will always install the most recent stable release. + +If you don't have `pip`_ installed, this `Python installation guide`_ +can guide you through the process. + + +.. _pip: https://pip.pypa.io +.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/ + + +From sources +------------ + +The sources for Triclour can be downloaded from the `Github repo`_. + +You can either clone the public repository: + +.. code-block:: console + + $ git clone git://github.com/ska-sa/tricolour + +Or download the `tarball`_: + +.. code-block:: console + + $ curl -OL https://github.com/ska-sa/triclour/tarball/master + +Once you have a copy of the source, you can install it with: + +.. code-block:: console + + $ python setup.py install + + +.. _Github repo: https://github.com/ska-sa/tricolour +.. _tarball: https://github.com/ska-sa/tricolour/tarball/master \ No newline at end of file diff --git a/docs/modules.rst b/docs/modules.rst index 30c4103..9ea100f 100644 --- a/docs/modules.rst +++ b/docs/modules.rst @@ -1,4 +1,4 @@ -tricolour +API ========= .. toctree:: diff --git a/docs/readme.rst b/docs/readme.rst new file mode 100644 index 0000000..6b2b3ec --- /dev/null +++ b/docs/readme.rst @@ -0,0 +1 @@ +.. include:: ../README.rst \ No newline at end of file diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..e33448d --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,13 @@ +===== +Usage +===== + +To use Triclour in a project:: + + import tricolour + +To use Tricolour in a command line + +.. code-block:: console + + $ tricolour --help \ No newline at end of file