Collapse parts of the documentation

docs/conf.py

@@ -33,34 +33,37 @@
 try:
     from sphinx_astropy.conf.v1 import *  # noqa
 except ImportError:
-    print('ERROR: the documentation requires the sphinx-astropy package to be installed')
+    print(
+        "ERROR: the documentation requires the sphinx-astropy package to be installed"
+    )
     sys.exit(1)
 
 # Get configuration information from setup.cfg
 from configparser import ConfigParser
+
 conf = ConfigParser()
 
-ON_RTD = os.environ.get('READTHEDOCS') == 'True'
-ON_TRAVIS = os.environ.get('TRAVIS') == 'true'
+ON_RTD = os.environ.get("READTHEDOCS") == "True"
+ON_TRAVIS = os.environ.get("TRAVIS") == "true"
 
-conf.read([os.path.join(os.path.dirname(__file__), '..', 'setup.cfg')])
-setup_cfg = dict(conf.items('metadata'))
+conf.read([os.path.join(os.path.dirname(__file__), "..", "setup.cfg")])
+setup_cfg = dict(conf.items("metadata"))
 
 # -- General configuration ----------------------------------------------------
 
 # By default, highlight as Python 3.
 # highlight_language = 'python3'
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.2'
+# needs_sphinx = '1.2'
 
 # To perform a Sphinx version check that needs to be more specific than
 # major.minor, call `check_sphinx_version("x.y.z")` here.
 # check_sphinx_version("1.2.1")
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns.append('_templates')
+exclude_patterns.append("_templates")
 
 # This is added to the end of RST files - a good place to put substitutions to
 # be used globally.
@@ -70,20 +73,19 @@
 # -- Project information ------------------------------------------------------
 
 # This does not *have* to match the package name, but typically does
-project = setup_cfg['name']
-author = setup_cfg['author']
-copyright = '{0}, {1}'.format(
-    datetime.datetime.now().year, setup_cfg['author'])
+project = setup_cfg["name"]
+author = setup_cfg["author"]
+copyright = "{0}, {1}".format(datetime.datetime.now().year, setup_cfg["author"])
 
 # 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.
 
-import_module(setup_cfg['name'])
-package = sys.modules[setup_cfg['name']]
+import_module(setup_cfg["name"])
+package = sys.modules[setup_cfg["name"]]
 
 # The short X.Y version.
-version = package.__version__.split('-', 1)[0]
+version = package.__version__.split("-", 1)[0]
 # The full version, including alpha/beta/rc tags.
 release = package.__version__
 
@@ -105,70 +107,70 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes. To override the custom theme, set this to the
 # name of a builtin theme or the name of a custom theme in html_theme_path.
-#html_theme = None
+# html_theme = None
 
 
 html_theme_options = {
-    'logotext1': 'HENDR',  # white,  semi-bold
-    'logotext2': 'ICS',  # orange, light
-    'logotext3': ':docs'   # white,  light
-    }
+    "logotext1": "HENDR",  # white,  semi-bold
+    "logotext2": "ICS",  # orange, light
+    "logotext3": ":docs",  # white,  light
+}
 
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# html_sidebars = {}
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = 'images/hendrics_logo.svg'
+html_logo = "images/hendrics_logo.svg"
 
 # 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 = 'images/hendrics_logo_32.png'
+html_favicon = "images/hendrics_logo_32.png"
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = ''
+# html_last_updated_fmt = ''
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = '{0} v{1}'.format(project, release)
+html_title = "{0} v{1}".format(project, release)
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = project + 'doc'
+htmlhelp_basename = project + "doc"
 
 
 # -- Options for LaTeX output -------------------------------------------------
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [('index', project + '.tex', project + u' Documentation',
-                    author, 'manual')]
+latex_documents = [
+    ("index", project + ".tex", project + " Documentation", author, "manual")
+]
 
 
 # -- Options for manual page output -------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [('index', project.lower(), project + u' Documentation',
-              [author], 1)]
+man_pages = [("index", project.lower(), project + " Documentation", [author], 1)]
 
 
+extensions += ["sphinx_toolbox.collapse"]
 # -- Options for the edit_on_github extension ---------------------------------
 
-if setup_cfg.get('edit_on_github').lower() == 'true':
-
-    extensions += ['sphinx_astropy.ext.edit_on_github']
+if setup_cfg.get("edit_on_github").lower() == "true":
+    extensions += ["sphinx_astropy.ext.edit_on_github"]
 
-    edit_on_github_project = setup_cfg['github_project']
+    edit_on_github_project = setup_cfg["github_project"]
     edit_on_github_branch = "main"
 
     edit_on_github_source_root = ""
     edit_on_github_doc_root = "docs"
 
 # -- Resolving issue number to links in changelog -----------------------------
-github_issues_url = 'https://github.com/{0}/issues/'.format(setup_cfg['github_project'])
+github_issues_url = "https://github.com/{0}/issues/".format(setup_cfg["github_project"])
 
 # -- Turn on nitpicky mode for sphinx (to warn about references not found) ----
 #
@@ -197,31 +199,35 @@
 #     nitpick_ignore.append((dtype, six.u(target)))
 
 if not ON_RTD and not ON_TRAVIS:
-    scripts = dict(conf.items('options.entry_points'))['console_scripts']
-
-    scripts = dict([(l.strip() for l in line.split("="))
-                    for line in scripts.split('\n')
-                    if line.strip() != ''])
+    scripts = dict(conf.items("options.entry_points"))["console_scripts"]
+
+    scripts = dict(
+        [
+            (l.strip() for l in line.split("="))
+            for line in scripts.split("\n")
+            if line.strip() != ""
+        ]
+    )
     import subprocess as sp
-    cli_file = os.path.join(os.getcwd(), 'scripts', 'cli.rst')
-    if os.path.exists(cli_file):
 
-        with open(cli_file, 'w') as fobj:
+    cli_file = os.path.join(os.getcwd(), "scripts", "cli.rst")
+    if os.path.exists(cli_file):
+        with open(cli_file, "w") as fobj:
             print("""Command line interface""", file=fobj)
             print("""======================\n""", file=fobj)
 
             for cl in sorted(scripts.keys()):
-                if cl.startswith('MP'):
+                if cl.startswith("MP"):
                     continue
                 print(cl, file=fobj)
-                print('-' * len(cl), file=fobj)
+                print("-" * len(cl), file=fobj)
                 print(file=fobj)
-                print('::', file=fobj)
+                print("::", file=fobj)
                 print(file=fobj)
-                lines = sp.check_output([cl, '--help']).decode().split('\n')
+                lines = sp.check_output([cl, "--help"]).decode().split("\n")
                 for l in lines:
-                    if l.strip() == '':
+                    if l.strip() == "":
                         print(file=fobj)
                     else:
-                        print('    ' + l, file=fobj)
+                        print("    " + l, file=fobj)
                 print(file=fobj)

docs/index.rst

@@ -58,87 +58,87 @@ HENDRICS 8.0.0rc1
 + NASA's IXPE added to supported missions
 + Better support of Stingray's native file formats
 
+Older releases
+~~~~~~~~~~~~~~
 
-HENDRICS 7.0
-~~~~~~~~~~~~
+.. collapse:: **HENDRICS 7.0**
 
-+ Based on `Stingray 1.0 <https://github.com/StingraySoftware/stingray/releases/tag/v1.0>`__, bringing a huge bump in performance
-+ Following Astropy, Numpy and Scipy, HENDRICS 7.0 is only compatible with Python >3.8
-+ Accepts many more file formats for round-trip of Stingray objects, thanks to the new functionality of Stingray.
-+ Energy-filtered periodograms
-+ A wider range of normalizations available for both ``HENfold`` and ``HENphaseogram``, with more options (e.g. smoothing) and higher-contrast color map by default
-+ Many fixes to mission-specific files
-+ Better info returned by Z/EF searches, including pulse amplitude estimates
-+ New upper limit functionality in Z/EF searches with no candidates
-+ ``HENplot`` now estimates the error of frequency and frequency derivative searches returned by ``HENzsearch``  and ``HENefsearch`` with option ``--fast``
-+ Add ability to split files at a given MJD
+    + Based on `Stingray 1.0 <https://github.com/StingraySoftware/stingray/releases/tag/v1.0>`__, bringing a huge bump in performance
+    + Following Astropy, Numpy and Scipy, HENDRICS 7.0 is only compatible with Python >3.8
+    + Accepts many more file formats for round-trip of Stingray objects, thanks to the new functionality of Stingray.
+    + Energy-filtered periodograms
+    + A wider range of normalizations available for both ``HENfold`` and ``HENphaseogram``, with more options (e.g. smoothing) and higher-contrast color map by default
+    + Many fixes to mission-specific files
+    + Better info returned by Z/EF searches, including pulse amplitude estimates
+    + New upper limit functionality in Z/EF searches with no candidates
+    + ``HENplot`` now estimates the error of frequency and frequency derivative searches returned by ``HENzsearch``  and ``HENefsearch`` with option ``--fast``
+    + Add ability to split files at a given MJD
 
 
-HENDRICS 6.0
-~~~~~~~~~~~~
+.. collapse:: **HENDRICS 6.0**
 
-+ Much Improved mission support
-+ Lots of performance improvements with large datasets
-+ Improved simulation and upper limit determination for Z searches
-+ Improved candidate searching in Z searches
-+ Lots of documentation fixes
+    + Much Improved mission support
+    + Lots of performance improvements with large datasets
+    + Improved simulation and upper limit determination for Z searches
+    + Improved candidate searching in Z searches
+    + Lots of documentation fixes
 
-HENDRICS 5.0
-~~~~~~~~~~~~
-More improvements to pulsar functionalities:
+.. collapse:: **HENDRICS 5.0**
 
-+ The accelerated search from Ransom+2002 is now available, to search the f-fdot space through Fourier analysis. It is highly performant but still needs some work. Please consider it experimental.
-+ A much faster folding algorithm (See Bachetti+2020, ApJ) is now available, allowing to reduce the computing time of Z searches by a factor ~10, while simultaneously searching a 2D space of frequency and fdot. Select with ``--fast`` option
-+ The classic Fast Folding Algorithm (Staelin 1969) is also available, to allow for extra-fast searches at low frequencies. However, this does not allow for "accelerated" searches on fdot. Also experimental and probably worth of further optimization.
+    More improvements to pulsar functionalities:
 
-Developed as part of CICLOPS -- Citizen Computing Pulsar Search, a project supported by *POR FESR Sardegna 2014 – 2020 Asse 1 Azione 1.1.3* (code RICERCA_1C-181), call for proposal "Aiuti per Progetti di Ricerca e Sviluppo 2017" managed by Sardegna Ricerche.
+    + The accelerated search from Ransom+2002 is now available, to search the f-fdot space through Fourier analysis. It is highly performant but still needs some work. Please consider it experimental.
+    + A much faster folding algorithm (See Bachetti+2020, ApJ) is now available, allowing to reduce the computing time of Z searches by a factor ~10, while simultaneously searching a 2D space of frequency and fdot. Select with ``--fast`` option
+    + The classic Fast Folding Algorithm (Staelin 1969) is also available, to allow for extra-fast searches at low frequencies. However, this does not allow for "accelerated" searches on fdot. Also experimental and probably worth of further optimization.
 
+    Developed as part of CICLOPS -- Citizen Computing Pulsar Search, a project supported by *POR FESR Sardegna 2014 – 2020 Asse 1 Azione 1.1.3* (code RICERCA_1C-181), call for proposal "Aiuti per Progetti di Ricerca e Sviluppo 2017" managed by Sardegna Ricerche.
 
-HENDRICS 4.0
-~~~~~~~~~~~~
-Lots of improvements to pulsar functionalities;
 
-.. Note ::
+.. collapse:: **HENDRICS 4.0**
 
-    Windows support for Python <3.6 was dropped. Most of the code will still work on old versions,
-    but the difficulty of tracking down library versions to test in Appveyor forces me
-    to drop the obsolescent versions of Python from testing on that architecture.
+    Lots of improvements to pulsar functionalities;
 
-HENDRICS 3.0
-~~~~~~~~~~~~
-The API is now rewritten to use
-`Stingray <https://github.com/StingraySoftware/stingray>`__ where possible.
-All MPxxx scripts are renamed to HENxxx.
+    .. Note ::
 
-Functionality additions:
+        Windows support for Python <3.6 was dropped. Most of the code will still work on old versions,
+        but the difficulty of tracking down library versions to test in Appveyor forces me
+        to drop the obsolescent versions of Python from testing on that architecture.
 
-+ Epoch folding search
-+ Z-squared search
-+ Color-Color Diagrams and Hardness-Intensity Diagrams
-+ Power spectral fitting
+.. collapse:: **HENDRICS 3.0**
 
-(MaLTPyNT) 2.0
-~~~~~~~~~~~~~~
-.. Note ::
+    The API is now rewritten to use
+    `Stingray <https://github.com/StingraySoftware/stingray>`__ where possible.
+    All MPxxx scripts are renamed to HENxxx.
+
+    Functionality additions:
+
+    + Epoch folding search
+    + Z-squared search
+    + Color-Color Diagrams and Hardness-Intensity Diagrams
+    + Power spectral fitting
+
+.. collapse:: **(MaLTPyNT) 2.0**
+
+    .. Note ::
 
-    MaLTPyNT provisionally accepted as an
-    `Astropy affiliated package <https://www.astropy.org/affiliated/index.html>`__
+        MaLTPyNT provisionally accepted as an
+        `Astropy affiliated package <https://www.astropy.org/affiliated/index.html>`__
 
 
-In preparation for the 2.0 release, the API has received some visible changes.
-Names do not have the `mp_` prefix anymore, as they were very redundant; the
-structure of the code base is now based on the AstroPy structure; tests have
-been moved and the documentation improved.
+    In preparation for the 2.0 release, the API has received some visible changes.
+    Names do not have the `mp_` prefix anymore, as they were very redundant; the
+    structure of the code base is now based on the AstroPy structure; tests have
+    been moved and the documentation improved.
 
-`HENexposure` is a new livetime correction script on sub-second timescales for
-NuSTAR. It will be able to replace `nulccorr`, and get results on shorter bin
-times, in observations done with a specific observing mode, where the observer
-has explicitly requested to telemeter all events (including rejected) and the
-user has run `nupipeline` with the `CLEANCOLS = NO` option.
-This tool is under testing.
+    `HENexposure` is a new livetime correction script on sub-second timescales for
+    NuSTAR. It will be able to replace `nulccorr`, and get results on shorter bin
+    times, in observations done with a specific observing mode, where the observer
+    has explicitly requested to telemeter all events (including rejected) and the
+    user has run `nupipeline` with the `CLEANCOLS = NO` option.
+    This tool is under testing.
 
-`HENfake` is a new script to create fake observation files in FITS format, for
-testing. New functions to create fake data will be added to `hendrics.fake`.
+    `HENfake` is a new script to create fake observation files in FITS format, for
+    testing. New functions to create fake data will be added to `hendrics.fake`.
 
 Preliminary notes
 -----------------