diff --git a/.gitignore b/.gitignore index f2f5437..d4bcdda 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,8 @@ __pycache__/ # C extensions *.so +.DS_Store + # Distribution / packaging .Python env/ @@ -105,3 +107,5 @@ ENV/ *~ *.swp *.swo + +.vscode/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..031caca --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,143 @@ +# Change Log + +This document records the main changes to the `python-template` code. + +## main + +[View commits since the last tag](https://github.com/sdss/python_template/compare/2.1.0...HEAD) + + +## 2.1.0 (2021-03-24) + +### 🚀 Added + +* GitHub workflow for testing. + +### ✨ Changed + +* Updated dependencies. +* Removed the requirements `docs` extra. Instead, documentation extra packages are defined in a `requirements.txt` in `docs/sphinx` and automatically installed in the RTD build. + +### 🔧 Fixed + +* Link to the standards in the README. + +[View commits](https://github.com/sdss/python_template/compare/2.0.0...2.1.0) + + +## 2.0.0 (2020-04-13) + +### ✨ Changed + +* Dropped support for Python 2. +* Move style guide to root level. +* Use `setup.cfg` for packaging and configuration of `pytest`, `flake8`, `isort`, and `coverage`. +* Move `tests` outside of the package to simplify packaging. +* Replace `utils` with [sdsstools](https://github.com/sdss/sdsstools). +* Remove use of `bumpversion`. Instead, get the package version using `sdsstools.get_package_version`. +* Updated the template Sphinx docs. +* Updated style guide and documentation. +* Allow to choose between setuptools and poetry. +* Allow to choose between `sphinx-bootstrap-theme` and `alabaster`. + +[View commits](https://github.com/sdss/python_template/compare/1.0.6...2.0.0) + + +## 1.0.6 (2019-12-31) + +### 🚀 Added + +* Avoid connecting more than one console handler to the warnings log. + +### 🔧 Fixed + +* Do not modify the record when formatting it, in case that record is also output in other handlers. + +[View commits](https://github.com/sdss/python_template/compare/1.0.5...1.0.6) + + +## 1.0.5 (2019-05-13) + +### Backward incompatible changes + +* The default path for the user configuration file is now `~/.config//.yml`. + +### 🚀 Added + +* Better handling of configuration files. An environment variable `$_CONFIG_PATH` (e.g., `$MYPYTHON_CONFIG_PATH`) can be defined to point to the user configuration file. If defined, this path overrides the default location. + +### ✨ Changed + +* Modified logger to deal with warnings. Added critical level printing. Fixes #12 and #13. + +### 🔧 Fixed + +* Bug causing Python 2.7 templates to fail because `PercentStyle` is not available in `logging` module (thanks to @andycasey). + +[View commits](https://github.com/sdss/python_template/compare/1.0.4...1.0.5) + + +## 1.0.4 (2019-01-18) + +### ✨ Changed + +* Updated year in template to 2019. + +### 🔧 Fixed + +* More fixes to quotes in `module-whatis` in module file. + +[View commits](https://github.com/sdss/python_template/compare/1.0.3...1.0.4) + + +## 1.0.3 (2018-12-10) + +### 🔧 Fixed + +* Quotes in `module-whatis` in module file. + +[View commits](https://github.com/sdss/python_template/compare/1.0.2...1.0.3) + + +## 1.0.2 (2018-10-01) + +### 🔧 Fixed + +* Remove `from __future__ import unicode_literals` that made the package install fail under Python 2. See [#9](https://github.com/sdss/python_template/issues/9) for details. + +[View commits](https://github.com/sdss/python_template/compare/1.0.1...1.0.2) + + +## 1.0.1 (2018-07-30) + +### 🚀 Added + +* Added W0621 to disabled list in pylint. + +### ✨ Changed + +* Changed documentation font size. +* Modified code and readthedocs configuration to use Python 3.6. +* Remove logger warning monkeypatching since it conflicted when used with packages that provide a similar monkeypatching. Replaced with a custom `logging.warning` method that produces coloured warning output. +* The `package_name` specified when cookiecutting the template is applied in lowercase when creating the package but in ucfirst case when creating classes. +* Renamed `misc` to `utils`. + +### 🔧 Fixed + +* Problem importing matplotlib in docs. +* A typo in the definition of the warning format in the logger. +* A typo in the definition of the API exception. + +[View commits](https://github.com/sdss/python_template/compare/1.0.0...1.0.1) + + +## 1.0.0 (2018-01-31) + +### 🚀 Added + +* Initial release. +* Includes Travis CI, Read The Docs, Coverage, and Bumpversion integrations. +* Includes a logger and configuration library. +* Examples for Sphinx documentation and pytest. + +[View commits](https://github.com/sdss/python_template/compare/b726b904a601fe051b9db8dfd24fee59f70bc866...1.0.0) diff --git a/CHANGELOG.rst b/CHANGELOG.rst deleted file mode 100644 index b250906..0000000 --- a/CHANGELOG.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. _python-template-changelog: - -========== -Change Log -========== - -This document records the main changes to the python-template code. - - -.. _python-template-main: - -main ----- - -`View commits since the last tag `__. - - -.. _python-template-2.1.0: - -2.1.0 (2021-03-24) ------------------- - -Added -^^^^^ -* GitHub workflow for testing. - -Changed -^^^^^^^ -* Updated dependencies. -* Removed the requirements ``docs`` extra. Instead, documentation extra packages are defined in a ``requirements.txt`` in ``docs/sphinx`` and automatically installed in the RTD build. - -Fixed -^^^^^ -* Link to the standards in the README. - -`View commits `__. - - -.. _python-template-2.0.0: - -2.0.0 (2020-04-13) ------------------- - -Changed -^^^^^^^ -* Dropped support for Python 2. -* Move style guide to root level. -* Use ``setup.cfg`` for packaging and configuration of ``pytest``, ``flake8``, ``isort``, and ``coverage``. -* Move ``tests`` outside of the package to simplify packaging. -* Replace ``utils`` with `sdsstools `__. -* Remove use of ``bumpversion``. Instead, get the package version using ``sdsstools.get_package_version``. -* Updated the template Sphinx docs. -* Updated style guide and documentation. -* Allow to choose between setuptools and poetry. -* Allow to choose between ``sphinx-bootstrap-theme`` and ``alabaster``. - -`View commits `__. - - -.. _python-template-1.0.6: - -1.0.6 (2019-12-31) ------------------- - -Added -^^^^^ -* Avoid connecting more than one console handler to the warnings log. - -Fixed -^^^^^ -* Do not modify the record when formatting it, in case that record is also output in other handlers. - -`View commits `__. - - -.. _python-template-1.0.5: - -1.0.5 (2019-05-13) ------------------- - -Backward incompatible changes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* The default path for the user configuration file is now ``~/.config//.yml``. - -Added -^^^^^ -* Better handling of configuration files. An environment variable ``$_CONFIG_PATH`` (e.g., ``$MYPYTHON_CONFIG_PATH``) can be defined to point to the user configuration file. If defined, this path overrides the default location. - -Changed -^^^^^^^ -* Modified logger to deal with warnings. Added critical level printing. Fixes :issue:`12,13`. - -Fixed -^^^^^ -* Bug causing Python 2.7 templates to fail because ``PercentStyle`` is not available in ``logging`` module (thanks to :user:`andycasey`). - -`View commits `__. - - -.. _python-template-1.0.4: - -1.0.4 (2019-01-18) ------------------- - -Changed -^^^^^^^ -* Updated year in template to 2019. - -Fixed -^^^^^ -* More fixes to quotes in ``module-whatis`` in module file. - -`View commits `__. - - -.. _python-template-1.0.3: - -1.0.3 (2018-12-10) ------------------- - -Fixed -^^^^^ -* Quotes in ``module-whatis`` in module file. - -`View commits `__. - - -.. _python-template-1.0.2: - -1.0.2 (2018-10-01) ------------------- - -Fixed -^^^^^ -* Remove ``from __future__ import unicode_literals`` that made the package install fail under Python 2. See `#9 `__ for details. - -`View commits `__. - - -.. _python-template-1.0.1: - -1.0.1 (2018-07-30) ------------------- - -Added -^^^^^ -* Added W0621 to disabled list in pylint. - -Changed -^^^^^^^ -* Changed documentation font size. -* Modified code and readthedocs configuration to use Python 3.6. -* Remove logger warning monkeypatching since it conflicted when used with packages that provide a similar monkeypatching. Replaced with a custom ``logging.warning`` method that produces coloured warning output. -* The ``package_name`` specified when cookiecutting the template is applied in lowercase when creating the package but in ucfirst case when creating classes. -* Renamed ``misc`` to ``utils``. - -Fixed -^^^^^ -* Problem importing matplotlib in docs. -* A typo in the definition of the warning format in the logger. -* A typo in the definition of the API exception. - -`View commits `__. - - -.. _python-template-1.0.0: - -1.0.0 (2018-01-31) ------------------- - -Added -^^^^^ -* Initial release. -* Includes Travis CI, Read The Docs, Coverage, and Bumpversion integrations. -* Includes a logger and configuration library. -* Examples for Sphinx documentation and pytest. - -`View commits `__. diff --git a/LICENSE.md b/LICENSE similarity index 98% rename from LICENSE.md rename to LICENSE index b583b6f..48e6b95 100644 --- a/LICENSE.md +++ b/LICENSE @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2017, SDSS +Copyright (c) 2017-, SDSS All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/cookiecutter.json b/cookiecutter.json deleted file mode 100644 index 248b13d..0000000 --- a/cookiecutter.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "full_name": "John Doe", - "email": "myemail@here.com", - "package_name": "myproject", - "repo_name": "{{ cookiecutter.package_name }}", - "pip_name": "sdss-{{ cookiecutter.package_name }}", - "version": "0.1.0-alpha.0", - "year": "{% now 'utc', '%Y' %}", - "short_description": "Simple Template package for creating SDSS Python projects", - "packaging_system": ["setuptools", "poetry"], - "sphinx_template": ["sphinx-bootstrap", "alabaster"], - "use_releases": ["no", "yes"], - "create_git_repo": ["yes", "no"], - "exists_on_github": ["no", "yes"], - "github_organisation": "sdss", - "_copy_without_render": [ - "*/_templates/*.html", - ".github/workflows/*" - ] -} diff --git a/copier.yaml b/copier.yaml new file mode 100644 index 0000000..843da77 --- /dev/null +++ b/copier.yaml @@ -0,0 +1,90 @@ +project_name: + type: str + qmark: 📚 + help: The name of the project. Used as repository name, in documentation, and other places. + validator: >- + {% if project_name == "" %} + Answer must not be an empty string. + {% endif %} + +package_name: + type: str + qmark: 📦 + help: The name of the Python package to create. This is the import name and the name of the package in PyPI. + validator: >- + {% if package_name == "" %} + Answer must not be an empty string. + {% endif %} + +project_description: + type: str + qmark: 📝 + help: A short description of the project. + validator: >- + {% if project_description == "" %} + Answer must not be an empty string. + {% endif %} + +author_name: + type: str + qmark: 🙋 + help: The full name of the project maintainer. + validator: >- + {% if author_name == "" %} + Answer must not be an empty string. + {% endif %} + +author_email: + type: str + qmark: 📧 + help: The email of the project maintainer. + validator: >- + {% if author_email == "" %} + Answer must not be an empty string. + {% endif %} + +license: + type: str + qmark: ⚖️ + help: The license for the project. + default: BSD-3-Clause + choices: + - BSD-3-Clause + - GPL-3.0-or-later + - Apache-2.0 + - MIT + +github_organization: + type: str + qmark: 🐙 + help: The GitHub organization or user where the repository will be hosted. + default: sdss + +github_username: + type: str + qmark: 👤 + help: The GitHub username of the project maintainer. + +push_to_github: + type: bool + qmark: 🚀 + help: Whether to create a GitHub repository and push the initial commit (requires GitHub CLI). + default: false + +private_repository: + type: bool + qmark: 🔒 + help: Create a private GitHub repository? + default: false + when: '{{ push_to_github == true }}' + +sync_project: + type: bool + qmark: 🔄 + help: Whether to create a venv and sync the project after creation using uv. + default: true + +_subdirectory: template + +_tasks: + - command: ['{{ _copier_python }}', 'post_copy.py'] diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile deleted file mode 100644 index 5145a85..0000000 --- a/docs/sphinx/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 = BMO -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/sphinx/_static/custom.css b/docs/sphinx/_static/custom.css index c400728..9ea0f78 100644 --- a/docs/sphinx/_static/custom.css +++ b/docs/sphinx/_static/custom.css @@ -1,107 +1,43 @@ -body { color: #444444 !important; font-size: 14px} - -div.custom-warning { - background-color: #f7c589; - border-color: #f7c589; -} - -div.custom-warning { - background-color: #f7c589; - border-color: #f7c589; -} +/* This is the custom CSS for alabaster. The theme does not allow for it to be set differently. */ .red { - color: red; + color: red; } .green { - color: green; + color: green; } .pink { - color: pink; + color: pink; } .orange { - color: orange; + color: orange; } .purple { - color: purple; -} - -dl.attribute, dl.method { - display: block; - margin-left: 50px; -} - -footer a{ - - color: #4c72b0 !important; -} -a.reference { - color: #4c72b0 !important; + color: purple; } -blockquote p { - font-size: 14px !important; +a.reference > em { + font-style: normal !important; } -blockquote { - padding-top: 4px !important; - padding-bottom: 4px !important; - margin: 0 0 0px !important; +a.reference > code { + font-weight: inherit !important; + color: inherit; + background-color: inherit; } -code { - color: #49759c !important; - background-color: #ffffff !important; +ul, ol { + margin: 0px 0 0px 30px; } -.alert-info { - background-color: #adb8cb !important; - border-color: #adb8cb !important; - color: #2c3e50 !important; -} - -code.descname, code.descclassname { - color: #c42850 !important; -} - -code.descclassname + code.descname { - margin-left: -4px; - padding-left: 0px; -} - -span.sig-paren ~ em { - font-weight: 600; - font-family: sans-serif; - font-size: 9.5pt; +a.reference { + border-bottom: 0px; } -em.property { - font-weight: 600; - font-family: sans-serif; - font-size: 9.5pt; +td.field-body > ul > li > em { + font-style: normal !important; } - -/* .function dt { - padding-top: 150px; - margin-top: -150px; - -webkit-background-clip: content-box; - background-clip: content-box; -} */ - -.rubric > .class-header-no-toc { - font-size: 240%; - font-weight: 400; - /* padding-bottom: 20px; */ - display: inline-block; -} - -h1 { font-size: 240%; } -h2 { font-size: 180%; } -h3 { font-size: 150%; } -h4 { font-size: 120%; } -h5 { font-size: 90%; } -h6 { font-size: 80%; } diff --git a/docs/sphinx/_static/pygments.css b/docs/sphinx/_static/pygments.css deleted file mode 100644 index 0fa0bea..0000000 --- a/docs/sphinx/_static/pygments.css +++ /dev/null @@ -1,77 +0,0 @@ -.highlight .hll { background-color: #ffffcc } -.highlight { background: #f8f8f8; } -.highlight .c { color: #8f5902; font-style: italic } /* Comment */ -.highlight .err { color: #a40000; border: 1px solid #ef2929 } /* Error */ -.highlight .g { color: #000000 } /* Generic */ -.highlight .k { color: #204a87; font-weight: bold } /* Keyword */ -.highlight .l { color: #000000 } /* Literal */ -.highlight .n { color: #000000 } /* Name */ -.highlight .o { color: #ce5c00; font-weight: bold } /* Operator */ -.highlight .x { color: #000000 } /* Other */ -.highlight .p { color: #000000; font-weight: bold } /* Punctuation */ -.highlight .ch { color: #8f5902; font-style: italic } /* Comment.Hashbang */ -.highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */ -.highlight .cp { color: #8f5902; font-style: italic } /* Comment.Preproc */ -.highlight .cpf { color: #8f5902; font-style: italic } /* Comment.PreprocFile */ -.highlight .c1 { color: #8f5902; font-style: italic } /* Comment.Single */ -.highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */ -.highlight .gd { color: #a40000 } /* Generic.Deleted */ -.highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */ -.highlight .gr { color: #ef2929 } /* Generic.Error */ -.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ -.highlight .gi { color: #00A000 } /* Generic.Inserted */ -.highlight .go { color: #000000; font-style: italic } /* Generic.Output */ -.highlight .gp { color: #8f5902 } /* Generic.Prompt */ -.highlight .gs { color: #000000; font-weight: bold } /* Generic.Strong */ -.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ -.highlight .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */ -.highlight .kc { color: #204a87; font-weight: bold } /* Keyword.Constant */ -.highlight .kd { color: #204a87; font-weight: bold } /* Keyword.Declaration */ -.highlight .kn { color: #204a87; font-weight: bold } /* Keyword.Namespace */ -.highlight .kp { color: #204a87; font-weight: bold } /* Keyword.Pseudo */ -.highlight .kr { color: #204a87; font-weight: bold } /* Keyword.Reserved */ -.highlight .kt { color: #204a87; font-weight: bold } /* Keyword.Type */ -.highlight .ld { color: #000000 } /* Literal.Date */ -.highlight .m { color: #0000cf; font-weight: bold } /* Literal.Number */ -.highlight .s { color: #4e9a06 } /* Literal.String */ -.highlight .na { color: #c4a000 } /* Name.Attribute */ -.highlight .nb { color: #204a87 } /* Name.Builtin */ -.highlight .nc { color: #000000 } /* Name.Class */ -.highlight .no { color: #000000 } /* Name.Constant */ -.highlight .nd { color: #5c35cc; font-weight: bold } /* Name.Decorator */ -.highlight .ni { color: #ce5c00 } /* Name.Entity */ -.highlight .ne { color: #cc0000; font-weight: bold } /* Name.Exception */ -.highlight .nf { color: #000000 } /* Name.Function */ -.highlight .nl { color: #f57900 } /* Name.Label */ -.highlight .nn { color: #000000 } /* Name.Namespace */ -.highlight .nx { color: #000000 } /* Name.Other */ -.highlight .py { color: #000000 } /* Name.Property */ -.highlight .nt { color: #204a87; font-weight: bold } /* Name.Tag */ -.highlight .nv { color: #000000 } /* Name.Variable */ -.highlight .ow { color: #204a87; font-weight: bold } /* Operator.Word */ -.highlight .w { color: #f8f8f8; text-decoration: underline } /* Text.Whitespace */ -.highlight .mb { color: #0000cf; font-weight: bold } /* Literal.Number.Bin */ -.highlight .mf { color: #0000cf; font-weight: bold } /* Literal.Number.Float */ -.highlight .mh { color: #0000cf; font-weight: bold } /* Literal.Number.Hex */ -.highlight .mi { color: #0000cf; font-weight: bold } /* Literal.Number.Integer */ -.highlight .mo { color: #0000cf; font-weight: bold } /* Literal.Number.Oct */ -.highlight .sa { color: #4e9a06 } /* Literal.String.Affix */ -.highlight .sb { color: #4e9a06 } /* Literal.String.Backtick */ -.highlight .sc { color: #4e9a06 } /* Literal.String.Char */ -.highlight .dl { color: #4e9a06 } /* Literal.String.Delimiter */ -.highlight .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */ -.highlight .s2 { color: #4e9a06 } /* Literal.String.Double */ -.highlight .se { color: #4e9a06 } /* Literal.String.Escape */ -.highlight .sh { color: #4e9a06 } /* Literal.String.Heredoc */ -.highlight .si { color: #4e9a06 } /* Literal.String.Interpol */ -.highlight .sx { color: #4e9a06 } /* Literal.String.Other */ -.highlight .sr { color: #4e9a06 } /* Literal.String.Regex */ -.highlight .s1 { color: #4e9a06 } /* Literal.String.Single */ -.highlight .ss { color: #4e9a06 } /* Literal.String.Symbol */ -.highlight .bp { color: #3465a4 } /* Name.Builtin.Pseudo */ -.highlight .fm { color: #000000 } /* Name.Function.Magic */ -.highlight .vc { color: #000000 } /* Name.Variable.Class */ -.highlight .vg { color: #000000 } /* Name.Variable.Global */ -.highlight .vi { color: #000000 } /* Name.Variable.Instance */ -.highlight .vm { color: #000000 } /* Name.Variable.Magic */ -.highlight .il { color: #0000cf; font-weight: bold } /* Literal.Number.Integer.Long */ diff --git a/docs/sphinx/_templates/layout.html b/docs/sphinx/_templates/layout.html deleted file mode 100644 index 56464be..0000000 --- a/docs/sphinx/_templates/layout.html +++ /dev/null @@ -1,5 +0,0 @@ -{# layout.html #} -{# Import the theme's layout. #} -{% extends "!layout.html" %} - -{% set css_files = css_files + ['_static/custom.css', '_static/pygments.css'] %} diff --git a/docs/sphinx/changelog.md b/docs/sphinx/changelog.md new file mode 100644 index 0000000..ea758b9 --- /dev/null +++ b/docs/sphinx/changelog.md @@ -0,0 +1,4 @@ +(template-changelog)= + +```{include} ../../CHANGELOG.md +``` diff --git a/docs/sphinx/changelog.rst b/docs/sphinx/changelog.rst deleted file mode 100644 index fee2d8a..0000000 --- a/docs/sphinx/changelog.rst +++ /dev/null @@ -1,2 +0,0 @@ - -.. include:: ../../CHANGELOG.rst diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 72129a9..1d3f6d4 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -1,83 +1,75 @@ -# -*- coding: utf-8 -*- -# -# Marvin documentation build configuration file, created by -# sphinx-quickstart on Sun Apr 10 08:50:42 2016. -# -# 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 os -# Comment if you do not want to use bootstrap themes. -import sphinx_bootstrap_theme # Are we building in RTD? -on_rtd = os.environ.get('READTHEDOCS') == 'True' +on_rtd = os.environ.get("READTHEDOCS") == "True" + -# -- General configuration ------------------------------------------------ +# matplotlib.use('agg') -# 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 = [ - 'IPython.sphinxext.ipython_console_highlighting', - 'IPython.sphinxext.ipython_directive', 'sphinx_issues'] + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.autosummary", + "sphinx_autodoc_typehints", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx.ext.mathjax", + "sphinx.ext.intersphinx", + "myst_parser", + "sphinx_copybutton", +] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] + +pygments_style = "lovelace" +pygments_dark_style = "one-dark" # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: -# source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} -source_suffix = ['.rst', '.md'] -# source_suffix = '.rst' +# source_suffix = ['.rst', '.md'] +source_suffix = ".rst" -# The encoding of source files. -# source_encoding = 'utf-8-sig' +source_parsers = { + # '.md': 'recommonmark.parser.CommonMarkParser', +} # The master toctree document. -master_doc = 'index' +master_doc = "index" # General information about the project. -project = u'SDSS Python Template' -copyright = u'2017, SDSS Collaboration' -author = u'José Sánchez-Gallego et al.' +project = "python_template" +copyright = "{0}, {1}".format("2018-", "SDSS Collaboration") +author = "SDSS Collaboration" # 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 full version, including alpha/beta/rc tags. +release = "3.0.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' +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", +] # The reST default role (used for this markup: `text`) to use for all # documents. -# default_role = 'py:obj' +default_role = "obj" # If true, '()' will be appended to :func: etc. cross-reference text. # add_function_parentheses = True @@ -91,7 +83,7 @@ # show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] @@ -99,116 +91,46 @@ # 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 = False + # Intersphinx mappings -intersphinx_mapping = {'python': ('https://docs.python.org/3.6', None), - 'astropy': ('http://docs.astropy.org/en/latest', None), - 'numpy': ('http://docs.scipy.org/doc/numpy/', None), - 'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None)} +intersphinx_mapping = {} -autodoc_member_order = 'groupwise' +autodoc_mock_imports = ["_tkinter"] +autodoc_member_order = "groupwise" +autodoc_default_options = {"members": None, "show-inheritance": None} +# autodoc_typehints = "description" -napoleon_use_rtype = False -napoleon_use_ivar = True +simplify_optional_unions = True +typehints_use_signature_return = True -# Github repo -issues_github_path = 'sdss/python_template' +# napoleon_use_rtype = False +# napoleon_use_ivar = True + +copybutton_prompt_text = r">>> |\$ " +copybutton_prompt_is_regexp = True rst_epilog = """ -.. |numpy_array| replace:: Numpy array -.. _numpy_array: http://example.com/ -.. |HDUList| replace:: :class:`~astropy.io.fits.HDUList` +.. |python_template_version| replace:: 3.0.0 +.. default-role:: py:obj """ + # -- 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 = 'bootstrap' - -# 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 = "furo" +html_title = "Python template documentation" +html_logo = "_static/sdssv_logo.png" +html_favicon = "./_static/favicon.ico" html_theme_options = { - # Navigation bar title. (Default: ``project`` value) - 'navbar_title': "SDSS Python Template", - - # Tab name for entire site. (Default: "Site") - 'navbar_site_name': "Site", - - # A list of tuples containing pages or urls to link to. - # Valid tuples should be in the following forms: - # (name, page) # a link to a page - # (name, "/aa/bb", 1) # a link to an arbitrary relative url - # (name, "http://example.com", True) # arbitrary absolute url - # Note the "1" or "True" value above as the third argument to indicate - # an arbitrary url. - 'navbar_links': [ - ], - - # Render the next and previous page links in navbar. (Default: true) - 'navbar_sidebarrel': False, - - # Render the current pages TOC in the navbar. (Default: true) - 'navbar_pagenav': False, - - # Tab name for the current pages TOC. (Default: "Page") - 'navbar_pagenav_name': "Page", - - # Global TOC depth for "site" navbar tab. (Default: 1) - # Switching to -1 shows all levels. - 'globaltoc_depth': 2, - - # Include hidden TOCs in Site navbar? - # - # Note: If this is "false", you cannot have mixed ``:hidden:`` and - # non-hidden ``toctree`` directives in the same page, or else the build - # will break. - # - # Values: "true" (default) or "false" - 'globaltoc_includehidden': "false", - - # HTML navbar class (Default: "navbar") to attach to
element. - # For black navbar, do "navbar navbar-inverse" - 'navbar_class': "navbar", - - # Fix navigation bar to top of page? - # Values: "true" (default) or "false" - 'navbar_fixed_top': "false", - - # Location of link to source. - # Options are "nav" (default), "footer" or anything else to exclude. - 'source_link_position': "", - - # Bootswatch (http://bootswatch.com/) theme. - # - # Options are nothing (default) or the name of a valid theme - # such as "amelia" or "cosmo". - 'bootswatch_theme': "paper", - - # Choose Bootstrap version. - # Values: "3" (default) or "2" (in quotes) - 'bootstrap_version': "3", + "source_repository": "https://github.com/sdss/python_template/", + "source_branch": "main", + "source_directory": "docs/sphinx", } -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() - -# The name for this set of Sphinx documents. -# " v documentation" by default. -# html_title = u'Marvin v2.0.0' - -# 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 = '_static/sdssv_logo_small.png' - -# The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -html_favicon = '_static/favicon_sdssv.ico' - # 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". @@ -217,151 +139,4 @@ if on_rtd: html_static_path = [] else: - 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 None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -# html_last_updated_fmt = None - -# 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 = {'**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html']} -html_sidebars = {'**': ['localtoc.html']} - -# 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', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' -# html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -# 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 = 'Templatedoc' - -# -- 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, 'Marvin.tex', u'Marvin Documentation', -# u'Brian Cherinka, Brett Andrews, and José Sánchez-Gallego', '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, 'marvin', u'Marvin 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, 'Marvin', u'Marvin Documentation', -# author, 'Marvin', '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 + html_static_path = ["_static"] diff --git a/docs/sphinx/index.md b/docs/sphinx/index.md new file mode 100644 index 0000000..e9268d4 --- /dev/null +++ b/docs/sphinx/index.md @@ -0,0 +1,376 @@ + +# SDSS Python Template + +```{toctree} +:hidden: +Changelog +Style guide