sphinx-astropy-1.2/0000755000077000000240000000000013562620276014313 5ustar tomstaff00000000000000sphinx-astropy-1.2/.circleci/0000755000077000000240000000000013562620276016146 5ustar tomstaff00000000000000sphinx-astropy-1.2/.circleci/config.yml0000644000077000000240000000260413562607141020134 0ustar tomstaff00000000000000version: 2 jobs: build: docker: - image: continuumio/miniconda3 steps: - checkout - run: name: Conda setup command: | conda config --set always_yes yes --set changeps1 no conda update -n root conda - run: name: Run tests with Sphinx 2.0 command: | conda create -q -n sphinx20 sphinx=2.0 pytest source activate sphinx20 pip install . pytest sphinx_astropy - run: name: Run tests with Sphinx 1.8 command: | conda create -q -n sphinx18 sphinx=1.8 pytest source activate sphinx18 pip install . pytest sphinx_astropy - run: name: Run tests with Sphinx 1.7 command: | conda create -q -n sphinx17 sphinx=1.7 pytest source activate sphinx17 pip install . pytest sphinx_astropy - run : name: Run tests with developer version of Sphinx command: | conda create -q -n sphinx-dev pytest source activate sphinx-dev pip install git+https://github.com/sphinx-doc/sphinx.git#egg=sphinx pip install . pytest sphinx_astropy - run: name: Check setup.py metadata command: | python setup.py check --restructuredtext sphinx-astropy-1.2/.gitignore0000644000077000000240000000101413234373360016272 0ustar tomstaff00000000000000# Compiled files *.py[cod] *.a *.o *.so *.pyd __pycache__ # Ignore .c files by default to avoid including generated code. If you want to # add a non-generated .c extension, use `git add -f filename.c`. *.c # Other generated files MANIFEST # Sphinx _build _generated # Packages/installer info *.egg *.egg-info dist build eggs parts bin var sdist develop-eggs .installed.cfg distribute-*.tar.gz # Other .cache .tox .*.swp *~ .project .pydevproject .settings .coverage cover htmlcov # Mac OSX .DS_Store # PyCharm .idea sphinx-astropy-1.2/CHANGES.rst0000644000077000000240000000142413562614731016115 0ustar tomstaff00000000000000Changes in sphinx-astropy ========================= 1.2 (2019-11-12) ---------------- - Updated minimum required version of Sphinx to 1.7 as Numpydoc dropped support for Sphinx older than 1.6 and the inherit docstring feature is only available in Sphinx 1.7 or greater. [#19, #24] - Make sure all extensions are marked as parallel-safe. [#26] 1.1.1 (2019-02-21) ------------------ - Fix app.info() deprecation warning for Sphinx >= 1.6. [#17] 1.1 (2018-11-15) ---------------- - Added a new extension for controlling whether intersphinx is used on the command-line. - Added a new extension to give a clear warning if the _static folder is missing. 1.0 (2018-02-07) ---------------- - Initial standalone version of this package (formerly packaged as part of astropy-helpers) sphinx-astropy-1.2/LICENSE.rst0000644000077000000240000000273013234373360016124 0ustar tomstaff00000000000000Copyright (c) 2014-2018, Astropy Developers All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the Astropy Team nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. sphinx-astropy-1.2/MANIFEST.in0000644000077000000240000000013213234373360016040 0ustar tomstaff00000000000000include README.rst include CHANGES.rst include LICENSE.rst exclude *.pyc *.o prune build sphinx-astropy-1.2/PKG-INFO0000644000077000000240000000542313562620276015414 0ustar tomstaff00000000000000Metadata-Version: 1.1 Name: sphinx-astropy Version: 1.2 Summary: Sphinx extensions and configuration specific to the Astropy project Home-page: https://www.astropy.org Author: The Astropy Developers Author-email: astropy.team@gmail.com License: BSD Description: About ===== This package serves two purposes: it provides a default Sphinx configuration and set of extensions specific to the Astropy project, and it acts as a meta-package by installing all required Sphinx extensions for the core Astropy package and other packages. Sphinx configuration -------------------- The default Sphinx configuration can be imported by putting: .. code-block:: python from sphinx_astropy.conf import * at the top of your ``conf.py`` file. You can then override specific settings from this default configuration, such as adding extensions or intersphinx packages. To give a clearer error messages for users, you can instead write: .. code-block:: python try: from sphinx_astropy.conf import * except ImportError: print('ERROR: the documentation requires the sphinx-astropy package to be installed') sys.exit(1) Dependencies/extensions ----------------------- Installing **sphinx-astropy** will automatically install (if not already present): * `Sphinx `_ * `astropy-sphinx-theme `_ - the default 'bootstrap' theme use by Astropy and a number of affilited packages. * `sphinx-automodapi `_ - an extension that makes it easy to automatically generate API documentation. * `sphinx-gallery `_ - an extension to generate example galleries * `numpydoc `_ - an extension to parse docstrings in NumpyDoc format * `pillow `_ - a package to deal with images, used by some examples in the astropy core documentation. |CircleCI Status| .. |CircleCI Status| image:: https://circleci.com/gh/astropy/sphinx-astropy.svg?style=svg :target: https://circleci.com/gh/astropy/sphinx-astropy Platform: UNKNOWN Classifier: Intended Audience :: Developers Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 3 Classifier: Operating System :: OS Independent Classifier: License :: OSI Approved :: BSD License sphinx-astropy-1.2/README.rst0000644000077000000240000000355113254521076016002 0ustar tomstaff00000000000000 About ===== This package serves two purposes: it provides a default Sphinx configuration and set of extensions specific to the Astropy project, and it acts as a meta-package by installing all required Sphinx extensions for the core Astropy package and other packages. Sphinx configuration -------------------- The default Sphinx configuration can be imported by putting: .. code-block:: python from sphinx_astropy.conf import * at the top of your ``conf.py`` file. You can then override specific settings from this default configuration, such as adding extensions or intersphinx packages. To give a clearer error messages for users, you can instead write: .. code-block:: python try: from sphinx_astropy.conf import * except ImportError: print('ERROR: the documentation requires the sphinx-astropy package to be installed') sys.exit(1) Dependencies/extensions ----------------------- Installing **sphinx-astropy** will automatically install (if not already present): * `Sphinx `_ * `astropy-sphinx-theme `_ - the default 'bootstrap' theme use by Astropy and a number of affilited packages. * `sphinx-automodapi `_ - an extension that makes it easy to automatically generate API documentation. * `sphinx-gallery `_ - an extension to generate example galleries * `numpydoc `_ - an extension to parse docstrings in NumpyDoc format * `pillow `_ - a package to deal with images, used by some examples in the astropy core documentation. |CircleCI Status| .. |CircleCI Status| image:: https://circleci.com/gh/astropy/sphinx-astropy.svg?style=svg :target: https://circleci.com/gh/astropy/sphinx-astropy sphinx-astropy-1.2/setup.cfg0000644000077000000240000000144713562620276016142 0ustar tomstaff00000000000000[metadata] name = sphinx-astropy version = attr:sphinx_astropy.__version__ url = https://www.astropy.org author = The Astropy Developers author_email = astropy.team@gmail.com classifiers = Intended Audience :: Developers Programming Language :: Python Programming Language :: Python :: 2 Programming Language :: Python :: 3 Operating System :: OS Independent License :: OSI Approved :: BSD License license = BSD description = Sphinx extensions and configuration specific to the Astropy project long_description = file: README.rst [bdist_wheel] universal = 1 [options] zip_safe = False packages = find: install_requires = sphinx>=1.7 astropy-sphinx-theme numpydoc sphinx-automodapi sphinx-gallery pillow [options.package_data] sphinx_astropy = local/* [egg_info] tag_build = tag_date = 0 sphinx-astropy-1.2/setup.py0000755000077000000240000000077113562610540016026 0ustar tomstaff00000000000000#!/usr/bin/env python # Licensed under a 3-clause BSD style license - see LICENSE.rst import sys import setuptools from distutils.version import LooseVersion from setuptools import setup # Setuptools 30.3.0 or later is needed for setup.cfg options to be used if LooseVersion(setuptools.__version__) < LooseVersion('30.3.0'): sys.stderr.write("ERROR: sphinx-automodapi requires setuptools 30.3.0 or " "later (found {0})".format(setuptools.__version__)) sys.exit(1) setup() sphinx-astropy-1.2/sphinx_astropy/0000755000077000000240000000000013562620276017405 5ustar tomstaff00000000000000sphinx-astropy-1.2/sphinx_astropy/__init__.py0000644000077000000240000000002413562614731021511 0ustar tomstaff00000000000000__version__ = '1.2' sphinx-astropy-1.2/sphinx_astropy/conf/0000755000077000000240000000000013562620276020332 5ustar tomstaff00000000000000sphinx-astropy-1.2/sphinx_astropy/conf/__init__.py0000644000077000000240000000157513236667706022462 0ustar tomstaff00000000000000# This directory contains the default Sphinx configuration for the core Astropy # package and other packages that want to use the same configuration. Rather # than store the configuration in a single conf.py file, we store it in v?.py # files and import the latest one into sphinx_astropy.conf so that packages can # choose to use either to do: # # from sphinx_astropy.conf import * # # or: # # from sphinx_astropy.conf.v1 import * # # with the latter being the option to use for stability. The idea is that # we can still make small changes (mainly fixing bugs) to v1.py, but if we # make any big changes in future, we can create a new version that packages # can choose to opt-in to. To create a new default configuration, create a # v2.py file (either starting from a copy of v1.py or starting from # scratch), and change the import below to 'from .v2 import *'. from .v1 import * sphinx-astropy-1.2/sphinx_astropy/conf/v1.py0000644000077000000240000002533013562607141021231 0ustar tomstaff00000000000000# -*- coding: utf-8 -*- # Licensed under a 3-clause BSD style license - see LICENSE.rst # # Astropy shared Sphinx settings. These settings are shared between # astropy itself and affiliated packages. # # Note that not all possible configuration values are present in this file. # # All configuration values have a default; values that are commented out # serve to show the default. import os import warnings from os import path import sphinx from distutils.version import LooseVersion # -- General configuration ---------------------------------------------------- # The version check in Sphinx itself can only compare the major and # minor parts of the version number, not the micro. To do a more # specific version check, call check_sphinx_version("x.y.z.") from # your project's conf.py needs_sphinx = '1.7' on_rtd = os.environ.get('READTHEDOCS', None) == 'True' def check_sphinx_version(expected_version): sphinx_version = LooseVersion(sphinx.__version__) expected_version = LooseVersion(expected_version) if sphinx_version < expected_version: raise RuntimeError( "At least Sphinx version {0} is required to build this " "documentation. Found {1}.".format( expected_version, sphinx_version)) # Configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { 'python': ('https://docs.python.org/3/', (None, 'http://data.astropy.org/intersphinx/python3.inv')), 'pythonloc': ('http://docs.python.org/', path.abspath(path.join(path.dirname(__file__), '..', 'local', 'python3_local_links.inv'))), 'numpy': ('https://docs.scipy.org/doc/numpy/', (None, 'http://data.astropy.org/intersphinx/numpy.inv')), 'scipy': ('https://docs.scipy.org/doc/scipy/reference/', (None, 'http://data.astropy.org/intersphinx/scipy.inv')), 'matplotlib': ('https://matplotlib.org/', (None, 'http://data.astropy.org/intersphinx/matplotlib.inv')), 'astropy': ('http://docs.astropy.org/en/stable/', None), 'h5py': ('http://docs.h5py.org/en/stable/', None)} # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build'] # Add any paths that contain templates here, relative to this directory. # templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # The reST default role (used for this markup: `text`) to use for all # documents. Set to the "smart" one. default_role = 'obj' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # This is added to the end of RST files - a good place to put substitutions to # be used globally. rst_epilog = """ .. _Astropy: https://www.astropy.org """ suppress_warnings = ['app.add_directive', ] # -- Project information ------------------------------------------------------ # 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' # 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 = [] # -- Settings for extensions and extension options ---------------------------- # 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_astropy.ext.intersphinx_toggle', 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.viewcode', 'numpydoc', 'sphinx_automodapi.automodapi', 'sphinx_automodapi.smart_resolver', 'sphinx_astropy.ext.doctest', 'sphinx_astropy.ext.changelog_links', 'sphinx_astropy.ext.missing_static', 'sphinx.ext.mathjax'] try: import matplotlib.sphinxext.plot_directive extensions += [matplotlib.sphinxext.plot_directive.__name__] # AttributeError is checked here in case matplotlib is installed but # Sphinx isn't. Note that this module is imported by the config file # generator, even if we're not building the docs. except (ImportError, AttributeError): warnings.warn( "matplotlib's plot_directive could not be imported. " + "Inline plots will not be included in the output") # Don't show summaries of the members in each class along with the # class' docstring numpydoc_show_class_members = False autosummary_generate = True automodapi_toctreedirnm = 'api' # Class documentation should contain *both* the class docstring and # the __init__ docstring autoclass_content = "both" # Render inheritance diagrams in SVG graphviz_output_format = "svg" graphviz_dot_args = [ '-Nfontsize=10', '-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif', '-Efontsize=10', '-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif', '-Gfontsize=10', '-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif' ] # -- 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-astropy' # Custom sidebar templates, maps document names to template names. html_sidebars = { '**': ['localtoc.html'], 'search': [], 'genindex': [], 'py-modindex': [], } # 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. # We include by default the favicon that is in the bootstrap-astropy theme. import astropy_sphinx_theme html_theme_path = astropy_sphinx_theme.get_html_theme_path() html_favicon = os.path.join(html_theme_path[0], html_theme, 'static', 'astropy_logo.ico') # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = '%d %b %Y' # 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 = {} # 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 # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # 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 # -- Options for LaTeX output ------------------------------------------------ # The paper size ('letter' or 'a4'). #latex_paper_size = 'letter' # The font size ('10pt', '11pt' or '12pt'). #latex_font_size = '10pt' # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. latex_toplevel_sectioning = 'part' # If true, show page references after internal links. #latex_show_pagerefs = False # If true, show URL addresses after external links. #latex_show_urls = False latex_elements = {} # Additional stuff for the LaTeX preamble. latex_elements['preamble'] = r""" % Use a more modern-looking monospace font \usepackage{inconsolata} % The enumitem package provides unlimited nesting of lists and enums. % Sphinx may use this in the future, in which case this can be removed. % See https://bitbucket.org/birkenfeld/sphinx/issue/777/latex-output-too-deeply-nested \usepackage{enumitem} \setlistdepth{15} % In the parameters section, place a newline after the Parameters % header. (This is stolen directly from Numpy's conf.py, since it % affects Numpy-style docstrings). \usepackage{expdlist} \let\latexdescription=\description \def\description{\latexdescription{}{} \breaklabel} % Support the superscript Unicode numbers used by the "unicode" units % formatter \DeclareUnicodeCharacter{2070}{\ensuremath{^0}} \DeclareUnicodeCharacter{00B9}{\ensuremath{^1}} \DeclareUnicodeCharacter{00B2}{\ensuremath{^2}} \DeclareUnicodeCharacter{00B3}{\ensuremath{^3}} \DeclareUnicodeCharacter{2074}{\ensuremath{^4}} \DeclareUnicodeCharacter{2075}{\ensuremath{^5}} \DeclareUnicodeCharacter{2076}{\ensuremath{^6}} \DeclareUnicodeCharacter{2077}{\ensuremath{^7}} \DeclareUnicodeCharacter{2078}{\ensuremath{^8}} \DeclareUnicodeCharacter{2079}{\ensuremath{^9}} \DeclareUnicodeCharacter{207B}{\ensuremath{^-}} \DeclareUnicodeCharacter{00B0}{\ensuremath{^{\circ}}} \DeclareUnicodeCharacter{2032}{\ensuremath{^{\prime}}} \DeclareUnicodeCharacter{2033}{\ensuremath{^{\prime\prime}}} % Make the "warning" and "notes" sections use a sans-serif font to % make them stand out more. \renewenvironment{notice}[2]{ \def\py@noticetype{#1} \csname py@noticestart@#1\endcsname \textsf{\textbf{#2}} }{\csname py@noticeend@\py@noticetype\endcsname} """ # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_domain_indices = True # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None # -- Options for the linkcheck builder ---------------------------------------- # A timeout value, in seconds, for the linkcheck builder linkcheck_timeout = 60 sphinx-astropy-1.2/sphinx_astropy/ext/0000755000077000000240000000000013562620276020205 5ustar tomstaff00000000000000sphinx-astropy-1.2/sphinx_astropy/ext/__init__.py0000644000077000000240000000010213233636045022303 0ustar tomstaff00000000000000from __future__ import division, absolute_import, print_function sphinx-astropy-1.2/sphinx_astropy/ext/changelog_links.py0000644000077000000240000000577213562607141023715 0ustar tomstaff00000000000000# Licensed under a 3-clause BSD style license - see LICENSE.rst """ This sphinx extension makes the issue numbers in the changelog into links to GitHub issues. """ from __future__ import print_function import re from distutils.version import LooseVersion from docutils.nodes import Text, reference from sphinx import __version__ BLOCK_PATTERN = re.compile('\[#.+\]', flags=re.DOTALL) ISSUE_PATTERN = re.compile('#[0-9]+') def process_changelog_links(app, doctree, docname): for rex in app.changelog_links_rexes: if rex.match(docname): break else: # if the doc doesn't match any of the changelog regexes, don't process return from sphinx.util import logging info = logging.getLogger(__name__).info info('[changelog_links] Adding changelog links to "{0}"'.format(docname)) for item in doctree.traverse(): if not isinstance(item, Text): continue # We build a new list of items to replace the current item. If # a link is found, we need to use a 'reference' item. children = [] # First cycle through blocks of issues (delimited by []) then # iterate inside each one to find the individual issues. prev_block_end = 0 for block in BLOCK_PATTERN.finditer(item): block_start, block_end = block.start(), block.end() children.append(Text(item[prev_block_end:block_start])) block = item[block_start:block_end] prev_end = 0 for m in ISSUE_PATTERN.finditer(block): start, end = m.start(), m.end() children.append(Text(block[prev_end:start])) issue_number = block[start:end] refuri = app.config.github_issues_url + issue_number[1:] children.append(reference(text=issue_number, name=issue_number, refuri=refuri)) prev_end = end prev_block_end = block_end # If no issues were found, this adds the whole item, # otherwise it adds the remaining text. children.append(Text(block[prev_end:block_end])) # If no blocks were found, this adds the whole item, otherwise # it adds the remaining text. children.append(Text(item[prev_block_end:])) # Replace item by the new list of items we have generated, # which may contain links. item.parent.replace(item, children) def setup_patterns_rexes(app): app.changelog_links_rexes = [re.compile(pat) for pat in app.config.changelog_links_docpattern] def setup(app): app.connect('doctree-resolved', process_changelog_links) app.connect('builder-inited', setup_patterns_rexes) app.add_config_value('github_issues_url', None, True) app.add_config_value('changelog_links_docpattern', ['.*changelog.*', 'whatsnew/.*'], True) return {'parallel_read_safe': True, 'parallel_write_safe': True} sphinx-astropy-1.2/sphinx_astropy/ext/doctest.py0000644000077000000240000000364113233636045022224 0ustar tomstaff00000000000000# Licensed under a 3-clause BSD style license - see LICENSE.rst """ This is a set of three directives that allow us to insert metadata about doctests into the .rst files so the testing framework knows which tests to skip. This is quite different from the doctest extension in Sphinx itself, which actually does something. For astropy, all of the testing is centrally managed from py.test and Sphinx is not used for running tests. """ import re from docutils.nodes import literal_block from docutils.parsers.rst import Directive class DoctestSkipDirective(Directive): has_content = True def run(self): # Check if there is any valid argument, and skip it. Currently only # 'win32' is supported in astropy.tests.pytest_plugins. if re.match('win32', self.content[0]): self.content = self.content[2:] code = '\n'.join(self.content) return [literal_block(code, code)] class DoctestOmitDirective(Directive): has_content = True def run(self): # Simply do not add any content when this directive is encountered return [] class DoctestRequiresDirective(DoctestSkipDirective): # This is silly, but we really support an unbounded number of # optional arguments optional_arguments = 64 def setup(app): app.add_directive('doctest-requires', DoctestRequiresDirective) app.add_directive('doctest-skip', DoctestSkipDirective) app.add_directive('doctest-skip-all', DoctestSkipDirective) app.add_directive('doctest', DoctestSkipDirective) # Code blocks that use this directive will not appear in the generated # documentation. This is intended to hide boilerplate code that is only # useful for testing documentation using doctest, but does not actually # belong in the documentation itself. app.add_directive('testsetup', DoctestOmitDirective) return {'parallel_read_safe': True, 'parallel_write_safe': True} sphinx-astropy-1.2/sphinx_astropy/ext/edit_on_github.py0000644000077000000240000001346513562607141023547 0ustar tomstaff00000000000000# Licensed under a 3-clause BSD style license - see LICENSE.rst """ This extension makes it easy to edit documentation on github. It adds links associated with each docstring that go to the corresponding view source page on Github. From there, the user can push the "Edit" button, edit the docstring, and submit a pull request. It has the following configuration options (to be set in the project's ``conf.py``): * ``edit_on_github_project`` The name of the github project, in the form "username/projectname". * ``edit_on_github_branch`` The name of the branch to edit. If this is a released version, this should be a git tag referring to that version. For a dev version, it often makes sense for it to be "master". It may also be a git hash. * ``edit_on_github_source_root`` The location within the source tree of the root of the Python package. Defaults to "lib". * ``edit_on_github_doc_root`` The location within the source tree of the root of the documentation source. Defaults to "doc", but it may make sense to set it to "doc/source" if the project uses a separate source directory. * ``edit_on_github_docstring_message`` The phrase displayed in the links to edit a docstring. Defaults to "[edit on github]". * ``edit_on_github_page_message`` The phrase displayed in the links to edit a RST page. Defaults to "[edit this page on github]". * ``edit_on_github_help_message`` The phrase displayed as a tooltip on the edit links. Defaults to "Push the Edit button on the next page" * ``edit_on_github_skip_regex`` When the path to the .rst file matches this regular expression, no "edit this page on github" link will be added. Defaults to ``"_.*"``. """ import inspect import os import re import sys from docutils import nodes from sphinx import addnodes def import_object(modname, name): """ Import the object given by *modname* and *name* and return it. If not found, or the import fails, returns None. """ try: __import__(modname) mod = sys.modules[modname] obj = mod for part in name.split('.'): obj = getattr(obj, part) return obj except: return None def get_url_base(app): return 'https://github.com/%s/tree/%s/' % ( app.config.edit_on_github_project, app.config.edit_on_github_branch) def doctree_read(app, doctree): # Get the configuration parameters if app.config.edit_on_github_project == 'REQUIRED': raise ValueError( "The edit_on_github_project configuration variable must be " "provided in the conf.py") source_root = app.config.edit_on_github_source_root url = get_url_base(app) docstring_message = app.config.edit_on_github_docstring_message # Handle the docstring-editing links for objnode in doctree.traverse(addnodes.desc): if objnode.get('domain') != 'py': continue names = set() for signode in objnode: if not isinstance(signode, addnodes.desc_signature): continue modname = signode.get('module') if not modname: continue fullname = signode.get('fullname') if fullname in names: # only one link per name, please continue names.add(fullname) obj = import_object(modname, fullname) anchor = None if obj is not None: try: lines, lineno = inspect.getsourcelines(obj) except: pass else: anchor = '#L%d' % lineno if anchor: real_modname = inspect.getmodule(obj).__name__ path = '%s%s%s.py%s' % ( url, source_root, real_modname.replace('.', '/'), anchor) onlynode = addnodes.only(expr='html') onlynode += nodes.reference( reftitle=app.config.edit_on_github_help_message, refuri=path) onlynode[0] += nodes.inline( '', '', nodes.raw('', ' ', format='html'), nodes.Text(docstring_message), classes=['edit-on-github', 'viewcode-link']) signode += onlynode def html_page_context(app, pagename, templatename, context, doctree): if (templatename == 'page.html' and not re.match(app.config.edit_on_github_skip_regex, pagename)): doc_root = app.config.edit_on_github_doc_root if doc_root != '' and not doc_root.endswith('/'): doc_root += '/' doc_path = os.path.relpath(doctree.get('source'), app.builder.srcdir) url = get_url_base(app) page_message = app.config.edit_on_github_page_message context['edit_on_github'] = url + doc_root + doc_path context['edit_on_github_page_message'] = page_message def setup(app): app.add_config_value('edit_on_github_project', 'REQUIRED', True) app.add_config_value('edit_on_github_branch', 'master', True) app.add_config_value('edit_on_github_source_root', 'lib', True) app.add_config_value('edit_on_github_doc_root', 'doc', True) app.add_config_value('edit_on_github_docstring_message', '[edit on github]', True) app.add_config_value('edit_on_github_page_message', 'Edit This Page on Github', True) app.add_config_value('edit_on_github_help_message', 'Push the Edit button on the next page', True) app.add_config_value('edit_on_github_skip_regex', '_.*', True) app.connect('doctree-read', doctree_read) app.connect('html-page-context', html_page_context) return {'parallel_read_safe': True, 'parallel_write_safe': True} sphinx-astropy-1.2/sphinx_astropy/ext/intersphinx_toggle.py0000644000077000000240000000260313562607141024470 0ustar tomstaff00000000000000# Licensed under a 3-clause BSD style license - see LICENSE.rst """ The purpose of this extension is to provide a configuration value that can be used to disable intersphinx on the command-line without editing conf.py. To use, you can build documentation with:: sphinx-build ... -D disable_intersphinx=1 This is used e.g. by astropy-helpers when using the build_docs command. """ from __future__ import print_function from distutils.version import LooseVersion from sphinx import __version__ SPHINX_LT_18 = LooseVersion(__version__) < LooseVersion('1.8') def disable_intersphinx(app, config=None): from sphinx.util.console import bold from sphinx.util import logging info = logging.getLogger(__name__).info if app.config.disable_intersphinx: info(bold('disabling intersphinx...')) app.config.intersphinx_mapping.clear() def setup(app): # Note that the config-inited setting was only added in Sphinx 1.8. For # earlier versions we use builder-inited but we need to be careful in what # order the extensions are declared so that this happens before intersphinx. if SPHINX_LT_18: app.connect('builder-inited', disable_intersphinx) else: app.connect('config-inited', disable_intersphinx) app.add_config_value('disable_intersphinx', 0, True) return {'parallel_read_safe': True, 'parallel_write_safe': True} sphinx-astropy-1.2/sphinx_astropy/ext/missing_static.py0000644000077000000240000000220113562607141023566 0ustar tomstaff00000000000000# Licensed under a 3-clause BSD style license - see LICENSE.rst """ The purpose of this extension is to give a clear warning if sphinx is expecting a static directory to be present but it isn't. """ from __future__ import print_function import os from distutils.version import LooseVersion from sphinx import __version__ SPHINX_LT_18 = LooseVersion(__version__) < LooseVersion('1.8') WARNING_TEMPLATE = """ Note: The static directory '{0}' was not found. This is often because it is empty and you are using git. If so, you don't need it, so make sure it isn't included in the html_static_path setting in your conf.py file, otherwise Sphinx may fail the build if you are turning warnings into errors. """ def static_warning(app, config=None): from sphinx.util import logging info = logging.getLogger(__name__).info for directory in app.config.html_static_path: if not os.path.exists(directory): info(WARNING_TEMPLATE.format(directory)) def setup(app): app.connect('build-finished', static_warning) return {'parallel_read_safe': True, 'parallel_write_safe': True} sphinx-astropy-1.2/sphinx_astropy/local/0000755000077000000240000000000013562620276020477 5ustar tomstaff00000000000000sphinx-astropy-1.2/sphinx_astropy/local/python3_local_links.inv0000644000077000000240000000122213233636045025164 0ustar tomstaff00000000000000# Sphinx inventory version 2 # Project: Python # Version: 3.5 # The remainder of this file should be compressed using zlib. x0{b$.!YTUa*!Qq{h\;ٯgɁlv VA#jolGN dk~#k40Zv]'`Z*H? %Z_H{\aj% Gব,:j'/xU2(j%PR\7(j֥5J?,Cf/բO4FZsz ouЏO l;4`6yDMA-}Jwq!dj!#T" h2oS߈~` t8RwjnKcRxr?%+\Ob 3s˻`Vһv@>2b;!I,=Wh_'l!Q%^B#Ô }inuD#e³\:{tu;/wxy. !nX{0BzoH /LxA&UXS{⮸5ߣ\RBiJF?sphinx-astropy-1.2/sphinx_astropy/local/python3_local_links.txt0000644000077000000240000000540413233636045025215 0ustar tomstaff00000000000000# Sphinx inventory version 2 # Project: Python # Version: 2.7 and 3.5 # The remainder of this file should be compressed using zlib. # python2 only links cPickle py:module -1 2/library/pickle.html#module-cPickle - unicode py:function -1 2/library/functions.html#unicode - bsddb py:module -1 2/library/bsddb.html#module-bsddb - dict.has_key py:method -1 2/library/stdtypes.html#dict.has_key - dict.iteritems py:method -1 2/library/stdtypes.html#dict.iteritems - dict.iterkeys py:method -1 2/library/stdtypes.html#dict.iterkeys - dict.itervalues py:method -1 2/library/stdtypes.html#dict.itervalues - urllib2.urlopen py:function -1 2/library/urllib2.html#urllib2.urlopen - # python3 print() py:function -1 3/library/functions.html#print - # python3 collections.abc collections.Container py:class -1 3/library/collections.abc.html#collections.abc.Container - collections.Hashable py:class -1 3/library/collections.abc.html#collections.abc.Hashable - collections.Sized py:class -1 3/library/collections.abc.html#collections.abc.Sized - collections.Callable py:class -1 3/library/collections.abc.html#collections.abc.Callable - collections.Iterable py:class -1 3/library/collections.abc.html#collections.abc.Iterable - collections.Iterator py:class -1 3/library/collections.abc.html#collections.abc.Iterator - collections.Generator py:class -1 3/library/collections.abc.html#collections.abc.Generator - collections.Sequence py:class -1 3/library/collections.abc.html#collections.abc.Sequence - collections.MutableSequence py:class -1 3/library/collections.abc.html#collections.abc.MutableSequence - collections.ByteString py:class -1 3/library/collections.abc.html#collections.abc.ByteString - collections.Set py:class -1 3/library/collections.abc.html#collections.abc.Set - collections.MutableSet py:class -1 3/library/collections.abc.html#collections.abc.MutableSet - collections.Mapping py:class -1 3/library/collections.abc.html#collections.abc.Mapping - collections.MutableMapping py:class -1 3/library/collections.abc.html#collections.abc.MutableMapping - collections.MappingView py:class -1 3/library/collections.abc.html#collections.abc.MappingView - collections.ItemsView py:class -1 3/library/collections.abc.html#collections.abc.ItemsView - collections.KeysView py:class -1 3/library/collections.abc.html#collections.abc.KeysView - collections.ValuesView py:class -1 3/library/collections.abc.html#collections.abc.ValuesView - collections.Awaitable py:class -1 3/library/collections.abc.html#collections.abc.Awaitable - collections.Coroutine py:class -1 3/library/collections.abc.html#collections.abc.Coroutine - collections.AsyncIterable py:class -1 3/library/collections.abc.html#collections.abc.AsyncIterable - collections.AsyncIterator py:class -1 3/library/collections.abc.html#collections.abc.AsyncIterator - sphinx-astropy-1.2/sphinx_astropy/tests/0000755000077000000240000000000013562620276020547 5ustar tomstaff00000000000000sphinx-astropy-1.2/sphinx_astropy/tests/__init__.py0000644000077000000240000000000013234373360022641 0ustar tomstaff00000000000000sphinx-astropy-1.2/sphinx_astropy/tests/test_conf.py0000644000077000000240000000321013373337455023105 0ustar tomstaff00000000000000from distutils.version import LooseVersion from sphinx import __version__ SPHINX_LT_17 = LooseVersion(__version__) < LooseVersion('1.7') if SPHINX_LT_17: from sphinx import build_main as build_main_original # As of Sphinx 1.7, the first argument is now no longer ignored, so we # construct a wrapper for older versions. def build_main(argv=None): argv.insert(0, 'sphinx-build') return build_main_original(argv=argv) else: from sphinx.cmd.build import build_main BASIC_CONF = """ from sphinx_astropy.conf import * suppress_warnings = ['app.add_directive', 'app.add_node', 'app.add_role'] """ BASIC_INDEX = """ Title ===== Just a test """ def generate_files(tmpdir): with open(tmpdir.join('conf.py').strpath, 'w') as f: f.write(BASIC_CONF) with open(tmpdir.join('index.rst').strpath, 'w') as f: f.write(BASIC_INDEX) def test_conf(tmpdir): # Just make sure the docs build with the default sphinx-astropy configuration generate_files(tmpdir) src_dir = tmpdir.strpath html_dir = tmpdir.mkdir('html').strpath status = build_main(argv=['-W', '-b', 'html', src_dir, html_dir]) assert status == 0 def test_intersphinx_toggle(tmpdir, capsys): # Test the sphinx_astropy.ext.intersphinx_toggle extension generate_files(tmpdir) src_dir = tmpdir.strpath html_dir = tmpdir.mkdir('html').strpath status = build_main(argv=['-W', '-b', 'html', src_dir, html_dir, '-D', 'disable_intersphinx=1']) assert status == 0 captured = capsys.readouterr() assert 'disabling intersphinx' in captured.out assert 'loading intersphinx' not in captured.out sphinx-astropy-1.2/sphinx_astropy.egg-info/0000755000077000000240000000000013562620276021077 5ustar tomstaff00000000000000sphinx-astropy-1.2/sphinx_astropy.egg-info/PKG-INFO0000644000077000000240000000542313562620276022200 0ustar tomstaff00000000000000Metadata-Version: 1.1 Name: sphinx-astropy Version: 1.2 Summary: Sphinx extensions and configuration specific to the Astropy project Home-page: https://www.astropy.org Author: The Astropy Developers Author-email: astropy.team@gmail.com License: BSD Description: About ===== This package serves two purposes: it provides a default Sphinx configuration and set of extensions specific to the Astropy project, and it acts as a meta-package by installing all required Sphinx extensions for the core Astropy package and other packages. Sphinx configuration -------------------- The default Sphinx configuration can be imported by putting: .. code-block:: python from sphinx_astropy.conf import * at the top of your ``conf.py`` file. You can then override specific settings from this default configuration, such as adding extensions or intersphinx packages. To give a clearer error messages for users, you can instead write: .. code-block:: python try: from sphinx_astropy.conf import * except ImportError: print('ERROR: the documentation requires the sphinx-astropy package to be installed') sys.exit(1) Dependencies/extensions ----------------------- Installing **sphinx-astropy** will automatically install (if not already present): * `Sphinx `_ * `astropy-sphinx-theme `_ - the default 'bootstrap' theme use by Astropy and a number of affilited packages. * `sphinx-automodapi `_ - an extension that makes it easy to automatically generate API documentation. * `sphinx-gallery `_ - an extension to generate example galleries * `numpydoc `_ - an extension to parse docstrings in NumpyDoc format * `pillow `_ - a package to deal with images, used by some examples in the astropy core documentation. |CircleCI Status| .. |CircleCI Status| image:: https://circleci.com/gh/astropy/sphinx-astropy.svg?style=svg :target: https://circleci.com/gh/astropy/sphinx-astropy Platform: UNKNOWN Classifier: Intended Audience :: Developers Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 3 Classifier: Operating System :: OS Independent Classifier: License :: OSI Approved :: BSD License sphinx-astropy-1.2/sphinx_astropy.egg-info/SOURCES.txt0000644000077000000240000000141313562620276022762 0ustar tomstaff00000000000000.gitignore CHANGES.rst LICENSE.rst MANIFEST.in README.rst setup.cfg setup.py .circleci/config.yml sphinx_astropy/__init__.py sphinx_astropy.egg-info/PKG-INFO sphinx_astropy.egg-info/SOURCES.txt sphinx_astropy.egg-info/dependency_links.txt sphinx_astropy.egg-info/not-zip-safe sphinx_astropy.egg-info/requires.txt sphinx_astropy.egg-info/top_level.txt sphinx_astropy/conf/__init__.py sphinx_astropy/conf/v1.py sphinx_astropy/ext/__init__.py sphinx_astropy/ext/changelog_links.py sphinx_astropy/ext/doctest.py sphinx_astropy/ext/edit_on_github.py sphinx_astropy/ext/intersphinx_toggle.py sphinx_astropy/ext/missing_static.py sphinx_astropy/local/python3_local_links.inv sphinx_astropy/local/python3_local_links.txt sphinx_astropy/tests/__init__.py sphinx_astropy/tests/test_conf.pysphinx-astropy-1.2/sphinx_astropy.egg-info/dependency_links.txt0000644000077000000240000000000113562620276025145 0ustar tomstaff00000000000000 sphinx-astropy-1.2/sphinx_astropy.egg-info/not-zip-safe0000644000077000000240000000000113562620276023325 0ustar tomstaff00000000000000 sphinx-astropy-1.2/sphinx_astropy.egg-info/requires.txt0000644000077000000240000000012213562620276023472 0ustar tomstaff00000000000000sphinx>=1.7 astropy-sphinx-theme numpydoc sphinx-automodapi sphinx-gallery pillow sphinx-astropy-1.2/sphinx_astropy.egg-info/top_level.txt0000644000077000000240000000001713562620276023627 0ustar tomstaff00000000000000sphinx_astropy