From d5c97e44f3d629fba0604d9356529b8652f0b55c Mon Sep 17 00:00:00 2001 From: delucchi-cmu Date: Fri, 9 Feb 2024 12:16:09 -0500 Subject: [PATCH 1/2] Add copy button to readthedocs --- docs/catalogs/arguments.rst | 1 + docs/conf.py | 27 +++++++++++++++++++++------ docs/guide/contributing.rst | 30 +++++++++++++++--------------- docs/index.rst | 8 ++++---- 4 files changed, 41 insertions(+), 25 deletions(-) diff --git a/docs/catalogs/arguments.rst b/docs/catalogs/arguments.rst index b2ebb7ba..d7ab545e 100644 --- a/docs/catalogs/arguments.rst +++ b/docs/catalogs/arguments.rst @@ -220,6 +220,7 @@ There are several stages to the pipeline execution, and you can expect progress reporting to look like the following: .. code-block:: + :class: no-copybutton Mapping : 100%|██████████| 72/72 [58:55:18<00:00, 2946.09s/it] Binning : 100%|██████████| 1/1 [01:15<00:00, 75.16s/it] diff --git a/docs/conf.py b/docs/conf.py index 836f4b84..d7d1df2a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,16 +24,23 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ["sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx.ext.viewcode"] - -extensions.append("autoapi.extension") -extensions.append("nbsphinx") - templates_path = [] exclude_patterns = ["_build", "**.ipynb_checkpoints"] # This assumes that sphinx-build is called from the root directory master_doc = "index" +html_theme = "sphinx_rtd_theme" + +extensions = [ + "sphinx.ext.mathjax", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx_copybutton", + "autoapi.extension", + "nbsphinx", +] + +# -- autoapi configuration ---------------------------------------- # Remove 'view source code' from top of page (for html, not python) html_show_sourcelink = False # Remove namespaces from class/method signatures @@ -46,4 +53,12 @@ autoapi_member_order = "bysource" napoleon_google_docstring = True -html_theme = "sphinx_rtd_theme" + +# -- sphinx-copybutton configuration ---------------------------------------- +## sets up the expected prompt text from console blocks, and excludes it from +## the text that goes into the clipboard. +copybutton_exclude = ".linenos, .gp" +copybutton_prompt_text = ">> " + +## lets us suppress the copy button on select code blocks. +copybutton_selector = "div:not(.no-copybutton) > div.highlight > pre" diff --git a/docs/guide/contributing.rst b/docs/guide/contributing.rst index 13abf1bf..b6ca6c71 100644 --- a/docs/guide/contributing.rst +++ b/docs/guide/contributing.rst @@ -33,7 +33,7 @@ virtual environment. LINCC-Frameworks engineers primarily use `conda` to manage environments. If you have conda installed locally, you can run the following to create and activate a new environment. -.. code-block:: bash +.. code-block:: console >> conda create env -n python=3.10 >> conda activate @@ -42,7 +42,7 @@ create and activate a new environment. Once you have created a new environment, you can install this project for local development using the following commands: -.. code-block:: bash +.. code-block:: console >> pip install -e .'[dev]' >> pre-commit install @@ -70,19 +70,19 @@ Notes: `do not yet exist `_, so it's recommended to install via conda before proceeding to hipscat-import. - .. code-block:: bash + .. code-block:: console - $ conda config --add channels conda-forge - $ conda install healpy - $ git clone https://github.com/astronomy-commons/hipscat-import - $ cd hipscat-import - $ pip install -e . + >> conda config --add channels conda-forge + >> conda install healpy + >> git clone https://github.com/astronomy-commons/hipscat-import + >> cd hipscat-import + >> pip install -e . When installing dev dependencies, make sure to include the single quotes. - .. code-block:: bash + .. code-block:: console - $ pip install -e '.[dev]' + >> pip install -e '.[dev]' Testing ------------------------------------------------------------------------------- @@ -97,17 +97,17 @@ paths. These are defined in ``conftest.py`` files. They're powerful and flexible Please add or update unit tests for all changes made to the codebase. You can run unit tests locally simply with: -.. code-block:: bash +.. code-block:: console - pytest + >> pytest If you're making changes to the sphinx documentation (anything under ``docs``), you can build the documentation locally with a command like: -.. code-block:: bash +.. code-block:: console - cd docs - make html + >> cd docs + >> make html Create your PR ------------------------------------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 799e98d4..14e41452 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,7 @@ Installation We recommend installing in a virtual environment, like venv or conda. You may need to install or upgrade versions of dependencies to work with hipscat-import. -.. code-block:: bash +.. code-block:: console pip install hipscat-import @@ -21,10 +21,10 @@ need to install or upgrade versions of dependencies to work with hipscat-import. `do not yet exist `_, so it's recommended to install via conda before proceeding to hipscat-import. - .. code-block:: bash + .. code-block:: console - $ conda config --append channels conda-forge - $ conda install healpy + >> conda config --append channels conda-forge + >> conda install healpy Setting up a pipeline ------------------------------------------------------------------------------- From cb0e2d1569f55ccfcf23873875f4da5917b732bc Mon Sep 17 00:00:00 2001 From: delucchi-cmu Date: Fri, 9 Feb 2024 12:19:37 -0500 Subject: [PATCH 2/2] Add new requirement. --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index e4a22bb3..157d2f40 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,3 +5,4 @@ nbsphinx ipython jupytext jupyter +sphinx-copybutton \ No newline at end of file