COSMIC-PopSynth · katiebreivik · May 29, 2026 · May 29, 2026 · May 29, 2026 · May 29, 2026
diff --git a/docs/conf.py b/docs/conf.py
@@ -27,15 +27,6 @@
 sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
-# This is the expected signature of the handler for this event, cf doc
-def autodoc_skip_member_handler(app, what, name, obj, skip, options):
-    # Basic approach; you might want a regex instead
-    return name.startswith("test_")
-
-# Automatically called by sphinx at startup
-def setup(app):
-    # Connect the autodoc-skip-member event from apidoc to the callback
-    app.connect('autodoc-skip-member', autodoc_skip_member_handler)
 
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = '1.0'
@@ -44,17 +35,16 @@ def setup(app):
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
-    'sphinx.ext.autosummary',
     'sphinx.ext.inheritance_diagram',
     'sphinx.ext.linkcode',
     'sphinx.ext.ifconfig',
     'sphinx_automodapi.automodapi',
+    'sphinx_automodapi.smart_resolver',
     'sphinxcontrib.programoutput',
     'matplotlib.sphinxext.plot_directive',
     'IPython.sphinxext.ipython_console_highlighting',
@@ -74,8 +64,8 @@ def setup(app):
 
 # -- autodoc ------------------------------------
 
-autoclass_content = 'class'
-autodoc_default_flags = ['show-inheritance', 'members', 'inherited-members']
+autoclass_content = 'both'
+autodoc_default_flags = ['members', 'inherited-members', 'no-heading', 'no-inheritance-diagram']
 
 # -- sphinx_gallery -----------------------------
 
@@ -183,11 +173,15 @@ def setup(app):
         "color-brand-primary": "#3f95e1",
         "color-brand-content": "#3f95e1",
         "color-brand-visited": "#3f95e1",
+        "color-api-name": "#3f95e1",
+        "color-api-pre-name": "#3f95e1",
     },
     "dark_css_variables": {
         "color-brand-primary": "#e193ca",
         "color-brand-content": "#e193ca",
-        "color-brand-visited": "#e193ca"
+        "color-brand-visited": "#e193ca",
+        "color-api-name": "#e193ca",
+        "color-api-pre-name": "#e193ca",
     },
     "sidebar_hide_name": False,
     "footer_icons": [
@@ -377,57 +371,35 @@ def setup(app):
 # -- linkcode -----------------------------------------------------------------
 
 def linkcode_resolve(domain, info):
-    """Determine the URL corresponding to Python object
+    """function for linkcode sphinx extension"""
+    def find_func():
+        # find the installed module in sys module
+        sys_mod = sys.modules[info["module"]]
 
-    This code is stolen with thanks from the scipy team.
-    """
-    if domain != 'py':
-        return None
+        # use inspect to find the source code and starting line number
+        names = info["fullname"].split(".")
+        func = sys_mod
+        for name in names:
+            func = getattr(func, name)
 
-    modname = info['module']
-    fullname = info['fullname']
+        source_code, line_num = inspect.getsourcelines(func)
 
-    submod = sys.modules.get(modname)
-    if submod is None:
-        return None
+        # get the file name from the module
+        file = info["module"].split(".")[-1]
 
-    obj = submod
-    for part in fullname.split('.'):
-        try:
-            obj = getattr(obj, part)
-        except:
-            return None
-    # try and sneak past a decorator
-    try:
-        obj = obj.im_func.func_closure[0].cell_contents
-    except (AttributeError, TypeError):
-        pass
+        return file, line_num, line_num + len(source_code) - 1
 
-    try:
-        fn = inspect.getsourcefile(obj)
-    except:
-        fn = None
-    if not fn:
-        try:
-            fn = inspect.getsourcefile(sys.modules[obj.__module__])
-        except:
-            fn = None
-    if not fn:
+    # ensure it has the proper domain and has a module
+    if domain != 'py' or not info['module']:
         return None
 
+    # attempt to cleverly locate the function in the file
     try:
-        source, lineno = inspect.findsource(obj)
-    except:
-        lineno = None
-
-    if lineno:
-        linespec = "#L%d" % (lineno + 1)
-    else:
-        linespec = ""
-
-    fn = os.path.relpath(fn, start=os.path.dirname(cosmic.__file__))
-    if fn.startswith(os.path.pardir):
-        return None
-
-    return ("http://github.com/COSMIC-PopSynth/COSMIC/tree/%s/COSMIC/%s%s"
-            % (GWPY_VERSION['full-revisionid'], fn, linespec))
+        file, start, end = find_func()
+        # stitch together a github link with specific lines
+        filename = "cosmic/{}.py#L{}-L{}".format(file, start, end)
+
+    # if you can't find it in the file then just link to the correct file
+    except Exception as e:
+        filename = info['module'].replace('.', '/') + '.py'
+    return f"https://github.com/COSMIC-popsynth/COSMIC/blob/develop/src/{filename}"
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,17 +3,25 @@
 ##################
 Welcome to COSMIC!
 ##################
-COSMIC (Compact Object Synthesis and Monte Carlo Investigation Code) is a rapid binary population synthesis suite with a special focus of generating compact binary populations. 
 
 .. raw:: html
 
+    <p style="text-align: center;">
+        <code>COSMIC</code> (<b>C</b>ompact <b>O</b>bject <b>S</b>ynthesis and <b>M</b>onte Carlo <b>I</b>nvestigation <b>C</b>ode) is a rapid binary population synthesis suite with a special focus of generating compact binary populations. 
+    </p>
+
     <div class="toms-nav-container" style="margin-bottom:50px;">
         <div class="box toms-nav-box-blue" data-href="pages/install.html">Install COSMIC</div>
         <div class="box toms-nav-box-pink" data-href="pages/reference_material.html">Configurations and outputs</div>
         <div class="box toms-nav-box-blue" data-href="pages/runpop.html">Sampling populations</div>
         <div class="box toms-nav-box-pink" data-href="pages/examples.html">Evolving binaries</div>
     </div>
 
+.. figure:: _static/cosmic-colour.png
+    :align: center
+    :width: 50%
+    :alt: COSMIC logo
+
 .. toctree::
     :maxdepth: 2
     :hidden:
@@ -28,11 +36,4 @@ COSMIC (Compact Object Synthesis and Monte Carlo Investigation Code) is a rapid
     pages/cite
     pages/developers
     _generated/whats_new
-
-*****************
-API documentation
-*****************
-
-Please consult these pages for more precise details on the modules in COSMIC:
-
-* :ref:`modindex`
+    pages/api
diff --git a/docs/modules/evolve.rst b/docs/modules/evolve.rst
@@ -0,0 +1,9 @@
+**********************
+Evolution (``evolve``)
+**********************
+
+The ``evolve`` module contains the main functions for evolving binary systems.
+
+.. automodapi:: cosmic.evolve
+    :no-inheritance-diagram:
+    :no-heading:
diff --git a/docs/modules/output.rst b/docs/modules/output.rst
@@ -0,0 +1,9 @@
+****************************
+Output analysis (``output``)
+****************************
+
+The ``output`` module contains the main functions for analysing output from COSMIC.
+
+.. automodapi:: cosmic.output
+    :no-inheritance-diagram:
+    :no-heading:
diff --git a/docs/modules/plotting.rst b/docs/modules/plotting.rst
@@ -0,0 +1,9 @@
+********************************
+Plotting binaries (``plotting``)
+********************************
+
+The ``plotting`` module contains the main functions for plotting binaries from COSMIC.
+
+.. automodapi:: cosmic.plotting
+    :no-inheritance-diagram:
+    :no-heading:
diff --git a/docs/modules/sample.rst b/docs/modules/sample.rst
@@ -0,0 +1,46 @@
+*********************
+Sampling (``sample``)
+*********************
+
+The ``sample`` module contains the main functions for sampling binary systems.
+
+Initial binary tables
+---------------------
+
+.. automodapi:: cosmic.sample.initialbinarytable
+    :no-inheritance-diagram:
+    :no-heading:
+
+.. automodapi:: cosmic.sample.initialcmctable
+    :no-inheritance-diagram:
+    :no-heading:
+
+Independent sampler
+-------------------
+
+.. automodapi:: cosmic.sample.sampler.independent
+    :no-inheritance-diagram:
+    :no-heading:
+
+Multidimensional sampler
+------------------------
+
+.. automodapi:: cosmic.sample.sampler.multidim
+    :no-inheritance-diagram:
+    :no-heading:
+
+CMC related functions
+---------------------
+
+.. automodapi:: cosmic.sample.sampler.cmc
+    :no-inheritance-diagram:
+    :no-heading:
+
+.. automodapi:: cosmic.sample.cmc.elson
+    :no-inheritance-diagram:
+    :no-heading:
+
+.. automodapi:: cosmic.sample.cmc.king
+    :no-inheritance-diagram:
+    :no-heading:
+
diff --git a/docs/modules/utils.rst b/docs/modules/utils.rst
@@ -0,0 +1,9 @@
+*****************************
+Utility functions (``utils``)
+*****************************
+
+The ``utils`` module contains utility functions for use with COSMIC.
+
+.. automodapi:: cosmic.utils
+    :no-inheritance-diagram:
+    :no-heading:
diff --git a/docs/pages/about.rst b/docs/pages/about.rst
@@ -3,6 +3,11 @@
 #####
 About
 #####
+
+.. figure:: /_static/cosmic-colour.png
+   :alt: COSMIC logo
+   :align: center
+
 COSMIC (Compact Object Synthesis and Monte Carlo Investigation Code) is a rapid binary population synthesis suite with a special focus of generating compact binary populations. 
 
 COSMIC implements stellar evolution using the fitting formulae described in

diff --git a/docs/pages/api.rst b/docs/pages/api.rst
@@ -0,0 +1,16 @@
+******************
+Full API Reference
+******************
+
+This page contains detailed information for *every* function/class in ``COSMIC``. Use the links below to explore
+each module in detail
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Modules
+
+    ../modules/evolve
+    ../modules/sample
+    ../modules/output
+    ../modules/plotting
+    ../modules/utils
diff --git a/docs/pages/inifile.rst b/docs/pages/inifile.rst
@@ -17,8 +17,8 @@ The buttons below link to the most recent stable and unstable default inifiles f
 .. raw:: html
 
     <div class="toms-nav-container" style="margin-bottom: 3rem; height: 90px; grid-template-rows: 90px">
-        <div class="box" data-href="https://github.com/COSMIC-PopSynth/COSMIC/blob/v3.6.1/examples/Params.ini">Latest stable INIFILE</div>
-        <div class="box" data-href="https://github.com/COSMIC-PopSynth/COSMIC/blob/develop/examples/Params.ini">Latest development INIFILE</div>
+        <div class="box toms-nav-box-blue" data-href="https://github.com/COSMIC-PopSynth/COSMIC/blob/v3.6.1/examples/Params.ini">Latest stable INIFILE</div>
+        <div class="box toms-nav-box-pink" data-href="https://github.com/COSMIC-PopSynth/COSMIC/blob/develop/examples/Params.ini">Latest development INIFILE</div>
     </div>
 
 
@@ -31,6 +31,17 @@ How to use this page
 **Interactive config generator** - it can also be used interactively to generate your very own configuration file or BSE settings dictionary for use in running COSMIC.
 In each of the following sections you can edit the values of the parameter and the files at the end of the page will update in turn for you to copy. Enjoy configuring COSMIC!
 
+.. tip::
+
+    If you've forgotten what a parameter does and don't want to open the docs, you can always use the ``explain_setting`` function in the ``utils`` module to get a quick refresher on what a parameter does and what values it can take
+
+    .. code-block:: python
+
+        from cosmic.utils import explain_setting
+
+        explain_setting("kickflag")
+
+
 All available settings
 ======================
 

diff --git a/src/cosmic/evolve.py b/src/cosmic/evolve.py
@@ -46,7 +46,7 @@
                'Michael Zevin <zevin@northwestern.edu>',
                'digman.12@osu.edu',
                'Tom Wagg <tomjwagg@gmail.com>']
-__all__ = ['Evolve', 'read_tracks_for_METISSE']
+__all__ = ['Evolve', 'read_tracks_for_METISSE', 'populate_tracks']
 
 
 # Make this match the ordering of all_cols in bpp_array.f

diff --git a/src/cosmic/sample/cmc/elson.py b/src/cosmic/sample/cmc/elson.py
@@ -30,6 +30,10 @@
 __author__ = "Carl Rodriguez <carllouisrodriguez@gmail.com>"
 __credits__ = "Carl Rodriguez <carllouisrodriguez@gmail.com>"
 
+__all__ = ["M_enclosed", "phi_r", "rho_r", "virial_radius_analytic", "find_rmax_vir", "find_sigma_sqr",
+           "get_positions", "get_velocities", "get_velocities_plummer", "get_velocities_old",
+           "scale_pos_and_vel", "draw_r_vr_vt"]
+
 
 def M_enclosed(r, gamma, rho_0):
     """

diff --git a/src/cosmic/utils.py b/src/cosmic/utils.py
@@ -78,7 +78,7 @@
     "read_MIST_track",
     "read_other_track",
     "read_eep_directory",
-    "to_f2py_str_array"
+    "to_f2py_str_array",
     "explain_setting",
 ]