diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..bd0c7be --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,39 @@ +# Build and Deploy Sphinx Docs to GitHub Pages +# Workflow for building sphinx documentation remotely +# and deploying the static HTML to a GitHub Pages site. +# Note this approach does not require the static HTML +# files to be stored/pushed/committed to an alternate +# pages branch or anything like that. It uses GitHub +# Action artifacts... +name: Deploy Docs + +on: + workflow_dispatch: + pull_request: + release: + types: + - published + push: + branches: + - main + - dev + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: sphinx-notes/pages@v3 diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..27e349f --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,33 @@ +API +=== + + +Fetch +----- + +.. autosummary:: + :toctree: generated/ + + dreambank.available_datasets + dreambank.fetch + dreambank.read_dreams + dreambank.read_info + + +Curation +-------- + +.. autosummary:: + :toctree: generated/ + .. :nosignatures: + + dreambank.curation.load_source_repository + dreambank.curation.get_all_dataset_ids + dreambank.curation.fetch_grid_file + dreambank.curation.fetch_source_file + dreambank.curation.read_source_dreams_as_df + dreambank.curation.read_source_info_as_dict + dreambank.curation.write_source_registry + dreambank.curation.write_curated_registry + dreambank.curation.write_dreams_df_to_csv + dreambank.curation.write_info_dict_to_json diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..69ba5be --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,168 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +import time +import sys +from importlib.metadata import metadata +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parents[1].joinpath("src"))) +import dreambank + + +project = dreambank.__name__ +version = dreambank.__version__[:3] +release = dreambank.__version__ +author = metadata("dreambank").get("Author-email").split(" <")[0] +curryear = time.strftime("%Y") +copyright = f"2024-{curryear}, {author}" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + # "sphinx.ext.doctest", + # "sphinx.ext.viewcode", + "sphinx.ext.autodoc", # Core Sphinx library for auto html doc generation from docstrings + "sphinx.ext.autosummary", # Create neat summary tables for modules/classes/methods etc + "sphinx.ext.intersphinx", # Link to other project's documentation (see mapping below) + "sphinx.ext.autosectionlabel", + # "sphinx_autodoc_typehints", # Automatically document param types (less noise in class signature) + # "numpydoc", + "sphinx_copybutton", # Adds a copy button to code blocks (for pasting) + "sphinx_design", # more options for pydatasphinx theme, eg, dropdowns, tabs + # "sphinx.ext.linkcode", + # "jupyter_sphinx", +] + +# sphinx.ext.autosectionlabel option +# Make sure the target is unique +autosectionlabel_prefix_document = True +# autosectionlabel_maxdepth = 1 + +source_suffix = ".rst" +source_encoding = "utf-8" +# master_doc = "index" +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +# include_patterns = "**" +templates_path = ["_templates"] +rst_epilog = """ +.. |dreambank| replace:: `dreambank` + +.. role:: python(code) + :language: python + +""" + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" +html_title = f"dreambank v{release}" # defaults to " v documentation" +html_short_title = "dreambank" +html_logo = None +html_favicon = None +html_css_files = [] +html_static_path = ["_static"] +html_last_updated_fmt = "" # empty string is equivalent to "%b %d, %Y" +html_permalinks = True +html_domain_indices = True +html_use_index = False +html_show_sourcelink = False +html_show_copyright = False +html_show_sphinx = False +html_output_encoding = "utf-8" +html_sidebars = { + # "**": [], # remove sidebar from all pages + "usage": [], # remove sidebar from usage page + "contributing": [], # remove sidebar from contributing page +} +html_additional_pages = {} +# :html_theme.sidebar_secondary.remove: true + +# I think this is just for showing source? +html_context = { + # "github_url": "https://github.com", + "github_user": "DxELab", + "github_repo": "dreambank", + "github_version": "main", + "doc_path": "docs", + "default_mode": "auto", # light, dark, auto +} + + +# Full list: +# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#references +html_theme_options = { + "navigation_with_keys": False, + "external_links": [ + {"name": "Releases", "url": "https://github.com/DxELab/dreambank/releases"}, + ], + "header_links_before_dropdown": 4, + "navbar_start": ["navbar-logo"], # "version-switcher" + "navbar_center": ["navbar-nav"], + "navbar_end": ["navbar-icon-links"], + # "navbar_persistent": [], # Default is a nice search bubble that I otherwise don't get + "navbar_align": "left", # left/content/right + "search_bar_text": "Search...", + # "article_header_start": ["breadcrumbs"], + # "article_header_end": [], + # "article_footer_items": [], + "footer_start": ["last-updated"], # "search-field" "search-button" + "footer_center": [], + "footer_end": [], # "theme-switcher" + "content_footer_items": [], + "show_prev_next": False, + # "sidebarwidth": 230, + # "navbar_start": ["navbar-logo", "version-switcher"], + "show_version_warning_banner": True, + "announcement": "This project is being developed by the Dream Engineering Lab in collaboration with the Sleep and Dream Database.", + "show_nav_level": 1, + "show_toc_level": 1, # How many to show (rest are still uncollapsible) + "navigation_depth": 3, + "collapse_navigation": False, + # "secondary_sidebar_items": [], + # "secondary_sidebar_items": {"**": []}, + "use_edit_page_button": True, + # "use_repository_button": True, + # "icon_links_label": "Quick Links", + "icon_links": [ + { + "name": "dreambank on GitHub", + "url": "https://github.com/DxELab/dreambank", + "icon": "fa-brands fa-square-github", + "type": "fontawesome", + }, + ], +} + +# configure sphinx-copybutton +# https://github.com/executablebooks/sphinx-copybutton +# copybutton_prompt_text = r">>> |\.\.\. |\$ " +# copybutton_prompt_is_regexp = True + + +# -- Options for autosummary/autodoc output ------------------------------------ +# Generate the API documentation when building +autosummary_generate = True # Turn on sphinx.ext.autosummary +# autodoc_typehints = "description" +# autodoc_member_order = "groupwise" +autodoc_default_options = { + "members": True, + "member-order": "groupwise", + "undoc-members": False, +} + + +# -- Intersphinx ------------------------------------------------ + +intersphinx_mapping = { + "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None), + "pooch": ("https://www.fatiando.org/pooch/latest", None), + "python": ("https://docs.python.org/3", None), +} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..e2a4e50 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,47 @@ + +.. danger:: + + This project is in the planning stage of development. DO NOT USE! + + +.. image:: https://badge.fury.io/py/dreambank.svg + :target: https://badge.fury.io/py/dreambank + :alt: PyPI + +.. image:: https://img.shields.io/github/license/dxelab/dreambank.svg + :target: https://github.com/dxelab/dreambank/blob/master/LICENSE + :alt: License + +.. image:: https://pepy.tech/badge/dreambank/month + :target: https://pepy.tech/badge/dreambank/month + :alt: Downloads + +.. image:: https://github.com/dxelab/dreambank/actions/workflows/docs.yml/badge.svg + :target: https://github.com/dxelab/dreambank/actions + :alt: Docs test + + +--- + + +dreambank +--------- + +A tabular-formatted and version-controlled `DreamBank `_ access point. + +--- + +The primary purpose of |dreambank| is to curate a tabular version-controlled view of the `DreamBank `_ metadataset. + +The secondary purpose of |dreambank| is to provide a quick `DreamBank `_ data access point from Python. + +Any publications that utilized any of these datasets should cite the original DreamBank paper: + Domhoff, G. W., & Schneider, A. (2008). Studying dream content using the archive and search engine on DreamBank.net. *Consciousness and Cognition*, 17(4), 1238-1247. doi:`10.1016/j.concog.2008.06.010 `_ + + +.. toctree:: + :maxdepth: 2 + :hidden: + + usage + api diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..07824d0 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,30 @@ +Usage +===== + + +Installation +------------ + +.. code-block:: shell + + pip install dreambank + + +The |dreambank| package version corresponds to versions of the datasets. To get a specific version of the datasets, install a specific version of |dreambank|. For example: + +.. code-block:: shell + + pip install --force-reinstall dreambank==1.0 + + +Check your current version of |dreambank| in a Python session with ``print(dreambank.__version__)``. + + +Quick start +----------- + +.. code-block:: python + + import dreambank + dreams = dreambank.read_dreams("izzy22_25") + info = dreambank.read_info("izzy22_25")