{"id":18325405,"url":"https://github.com/nickhand/nbodykit-docs-bare","last_synced_at":"2025-04-09T15:41:45.692Z","repository":{"id":148831162,"uuid":"134344443","full_name":"nickhand/nbodykit-docs-bare","owner":"nickhand","description":"A trimmed down, demo version of the nbodykit documentation","archived":false,"fork":false,"pushed_at":"2018-07-03T00:39:23.000Z","size":78,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-15T09:34:46.786Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickhand.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-22T01:34:56.000Z","updated_at":"2018-07-03T00:39:24.000Z","dependencies_parsed_at":"2023-06-27T19:22:16.389Z","dependency_job_id":null,"html_url":"https://github.com/nickhand/nbodykit-docs-bare","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickhand%2Fnbodykit-docs-bare","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickhand%2Fnbodykit-docs-bare/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickhand%2Fnbodykit-docs-bare/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickhand%2Fnbodykit-docs-bare/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickhand","download_url":"https://codeload.github.com/nickhand/nbodykit-docs-bare/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248059926,"owners_count":21041050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T18:41:57.224Z","updated_at":"2025-04-09T15:41:45.668Z","avatar_url":"https://github.com/nickhand.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Setting up nbodykit documentation\n=================================\n\nThe documentation is built using Sphinx -- general documentation can be\nfound at http://www.sphinx-doc.org. The documentation is located in the\n``docs`` directory, and\n\n- the documentation files are located in the `docs/source`_ directory and are restructured text files\n- the configuration is controlled by `conf.py`_; this is generally the same template file with a few modifications for specific packages.\n- the main page of the documentation is `docs/source/index.rst`_, which sets up the structure of the documentation by linking to the other files via table of contents commands\n- the build process is controlled by `Makefile`_; this is also filled with template build commands, and we've added a few more for this package.\n\n\n.. _conf.py: docs/source/conf.py\n.. _Makefile: docs/Makefile\n.. _docs/source: docs/source\n.. _docs/source/index.rst: docs/source/index.rst\n\nBuild Instructions\n------------------\n\nTo build a local copy of the nbodykit docs, install the programs in\nenvironment.yml and run 'make html'. If you use the conda package manager\nthese commands suffice::\n\n  git clone git@github.com:nickhand/nbodykit-docs-bare.git\n  cd nbodykit/docs\n  conda env create --name nbodykitdocs -f environment.yml\n  source activate nbodykitdocs\n  make html\n  open build/html/index.html\n\nThe documenation can be cleaned using::\n\n  make clean\n\nThis uses `environment.yml`_ to install the necessary dependencies of nbodykit\nand the dependencies necessary to build the documentation. \n\n.. _environment.yml: docs/environment.yml \n\nConfiguration\n-------------\n\nThe configuration for the build process is handled by the `conf.py`_ file. This file \nis responsible for a few things: \n\n- loading the listed extensions\n- setting various parameter that control how the documentation\n- defining the html theme\n- automatically generating a restructured text file containing a list of modules and telling Sphinx to autogenerate the docs for each module\n\nWe'll expand on the last two points in the sections below. \n\nSetting the Theme\n^^^^^^^^^^^^^^^^^\n\nThere are various theme choices for the documentation. A common one is the \nRead the Docs (RTD) theme, which generates documentation that looks like https://sphinx-rtd-theme.readthedocs.io/.\nFor the nbodykit documentation, we used the `Sphinx Bootstrap theme`_, which lets you \nset any of the version 3 Bootstrap themes. We chose the `Readable`_ theme for its clarity.\nThis theme is chosen and configured near the bottom of the `conf.py`_ file, \nand the various options can be found in the documentation for the theme.\n\n.. _Sphinx Bootstrap theme: https://ryan-roemer.github.io/sphinx-bootstrap-theme/\n.. _Readable: https://bootswatch.com/3/readable/\n\nAuto-generating the Docs\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nIn `conf.py`_, we use the function `autogen_modules()` to automatically generate \nthe file `docs/source/api/modules.rst`. This file lists all of the modules in the package\nunder an `autosummary::` command. This command is described in the documentation here: \nhttp://www.sphinx-doc.org/en/master/ext/autosummary.html. By setting the ``toctree`` option\nof this command to ``_autosummary``, Sphinx will automatically generate stub .rst files for \neach module in the ``docs/source/api/_autosummary``. After running ``make html``, you should\nsee both the ``docs/source/api/modules.rst`` files and all of the corresponding .rst files\nin ``docs/source/api/_autosummary``.\n\nThis process allows us to dynamically generate the docs on the fly. With the documentation \ngenerated, I like to add explicit links to the relevant documentation from a single page\nwithin the documentation. In this case, it is `api.rst`_. For the single module `nbodykit.io`, \nthis page in the documentation will list out the name and a brief description of the \nspecific classes/functions\nthat we list, and it will be linked to the full documentation for that object.\n\n.. _api.rst: docs/source/api/api.rst\n\nUsing Jupyter Notebooks\n-----------------------\n\nThe documentation for any GitHub repo can be easily hosted for free on Read the Docs, but\nunfortunately, there is a rather short time limit for the documenation building process.\nThere are extensions that will show execute and show code snippets and output on the fly\nat build time, but generally this will make you run over the time limit on Read the Docs. \nTo get around this issue with nbodykit, we use the ``nbsphinx`` extension \nwhich lets you include executed Jupyter notebooks\nin your documentation. So to avoid the time limit, we execute and commit notebooks to the \nrepo, which are then displayed in the documentation without the code cells \nbeing executed again.\n\nThere is an example notebook at `docs/source/catalogs/reading.ipynb`_. This file \nis linked to from the main ``index.rst`` file. The documenation \nfor the extension is very handy and can be found at https://nbsphinx.readthedocs.io.\n\n.. _docs/source/catalogs/reading.ipynb: docs/source/catalogs/reading.ipynb\n\nWorkflow for editing notebooks\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nWe use the ``nbsphinx`` extension to include ``.ipynb`` files in the docs. A few useful things to know:\n\n1. **Hidden Cells**: You can include hidden cells in the notebook, which will not show up in the HTML output, by editing the cell metadata. Use View -\u003e Cell Toolbar -\u003e Edit Metadata, and then go to the cell you want, click edit metadata, and insert into the metadata dictionary the key/value pair: ``\"nbsphinx\" : \"hidden\"``.\n2. **ReST Cells**: You can include raw restructured text cells in the notebook, which will be converted properly. You must set the cell type to raw ReST. This can be done using:  View -\u003e Cell Toolbar -\u003e Raw Cell Format, and then going to the cell you want, and setting the type to ReST. \n3. **Linking to notebook files**: From other RST files, you can link to the notebooks via the ``ref`` directive. The important thing to remember is that you must use the full notebook file path, as if the top level directory is ``source``. So you can link to a notebook in the cookbook directory, using the path \"cookbook/lognormal-mocks.ipynb\".\n\nExecuting notebooks\n^^^^^^^^^^^^^^^^^^^\n\nTo execute all notebooks in the documentation before committing them or re-building \nthe docs, use::\n\n    python helper_scripts/run_notebooks.py\n\nor equivalently, you can use ``make ipynb``.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickhand%2Fnbodykit-docs-bare","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickhand%2Fnbodykit-docs-bare","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickhand%2Fnbodykit-docs-bare/lists"}