{"id":23085784,"url":"https://github.com/neurodatawithoutborders/nwb-overview","last_synced_at":"2026-02-02T05:06:24.540Z","repository":{"id":39879274,"uuid":"467987340","full_name":"NeurodataWithoutBorders/nwb-overview","owner":"NeurodataWithoutBorders","description":"Introduction to NWB software","archived":false,"fork":false,"pushed_at":"2025-02-10T22:34:06.000Z","size":31374,"stargazers_count":8,"open_issues_count":44,"forks_count":9,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-06-20T04:08:31.340Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://nwb-overview.readthedocs.io/","language":null,"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/NeurodataWithoutBorders.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,"zenodo":null}},"created_at":"2022-03-09T15:37:04.000Z","updated_at":"2025-04-07T00:32:49.000Z","dependencies_parsed_at":"2025-04-03T15:46:47.251Z","dependency_job_id":null,"html_url":"https://github.com/NeurodataWithoutBorders/nwb-overview","commit_stats":{"total_commits":256,"total_committers":14,"mean_commits":"18.285714285714285","dds":0.59375,"last_synced_commit":"a15cef5204b7b39ce35188df4748deb491728239"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":"readthedocs/tutorial-template","purl":"pkg:github/NeurodataWithoutBorders/nwb-overview","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeurodataWithoutBorders%2Fnwb-overview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeurodataWithoutBorders%2Fnwb-overview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeurodataWithoutBorders%2Fnwb-overview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeurodataWithoutBorders%2Fnwb-overview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NeurodataWithoutBorders","download_url":"https://codeload.github.com/NeurodataWithoutBorders/nwb-overview/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeurodataWithoutBorders%2Fnwb-overview/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29006081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T04:25:24.522Z","status":"ssl_error","status_checked_at":"2026-02-02T04:24:51.069Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-12-16T18:10:54.914Z","updated_at":"2026-02-02T05:06:24.447Z","avatar_url":"https://github.com/NeurodataWithoutBorders.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"Building the docs locally\n==========================\n\n.. code-block:: bash\n\n    sphinx-build -a docs/source build\n\n\nor\n\n.. code-block:: bash\n\n    cd docs\n    make html\n\nAnd to view the docs open ``build/html/index.html``.\n\n\nAdding a Community Tool\n=======================\n\nTo contribute a new tool to the list of analysis, visualization and data management tools, please create a pull request to this repo. Adding a tool requires the following steps.\n\n**Step 1:** Create a new folder for your tool in ``docs/source/tools/\u003cmytool\u003e`` with the name of your tool\n\n**Step 2:** Create a new file ``docs/source/tools/\u003cmytool\u003e/\u003cmytool\u003e.rst`` for your tool and copy the following template to that file\n\n.. code-block::\n\n    .. _analysistools-\u003cmytool\u003e:\n\n    \u003cmytoolname\u003e\n    ------------\n\n    .. short_description_start\n\n    :ref:`analysistools-\u003cmytool\u003e` \u003cbriefly describe your tool\u003e :bdg-link-primary:`Docs \u003cmydocs\u003e` :bdg-link-primary:`Source \u003cmysoure\u003e`.\n\n    .. short_description_end\n\n    .. image:: \u003cmyimgage\u003e\n        :class: align-left\n        :width: 400\n\n**Step 3:** Update the ``\u003cmy*\u003e`` parts and add a brief description of your tool as well as an image for your tool.\n\n**Step 4:** You may add additional sections as appropriate to the page, e.g., to describe tool features, usage, or installation. In particular, also consider adding a section on ``Compatability with NWB`` to describe how your tools integrate with NWB (e.g., does your tool support read/write/update of specific neurodata_types in NWB and does your tool require any extensions).\n\n**Step 5:** Add your tool to the tools index page. For analysis and visualization, edit  ``docs/source/tools/analysis_tools_home.rst`` and for data acquistion and control tools edit ``docs/source/tools/acquisition_tools_home.rst``\n\n**Step 5.1:** Add your tool to the toctree at the top of the page tools index page to ensure the tool gets listed in the main menu\n\n**Step 5.2:** In the section that best fits your tool on the tools index page add the following and again update the ``\u003cmy*\u003e`` marked parts.\n\n.. code-block::\n\n    .. image:: \u003cmytool\u003e/\u003cmyimage\u003e\n        :class: align-left\n        :width: 180\n\n    .. include::  \u003cmytool\u003e/\u003cmytool.rst\u003e\n            :start-after: .. short_description_start\n            :end-before: .. short_description_end\n\nWith ``.. include`` directive with the ``start-after`` and ``end-before`` parameters, Sphinx will automatically include the short description from your doc so the glossary will automatically be updated as you make changes in the main document of your your tool.\n\n.. note::\n\n    Depending on how long your and the previous tool description are, you may need to add some empty lines in HTML before/after your entry to ensure the overview displays correctly. You can add lines in HTML by adding the following in the file\n\n.. code-block::\n\n    .. raw:: html\n\n        \u003cbr /\u003e\n        \u003cbr /\u003e\n\n.. note::\n\n    Latex does not support ``gif`` images. If you need to use ``gif`` images then you should place them in a ``.. only:: html`` directive and provide a corresponding ``.. only:: latex`` directive with the appropriate content for Latex PDF builds.\n\n\n\n**Step 6a:** Build the docs and and review your changes via\n\n.. code-block::\n\n    cd docs\n    make html\n    open build/html/index.html\n\n**Step 7** Create a pull request to this repo with your changes\n\n\nAdding a Community Project\n==========================\n\nTo contribute a new project to the community gallery, please create a pull request to this repo. Adding a tool requires the following steps.\n\n**Step 1:** Create a new entry on the ``docs/source/community_gallery/community_gallery.rst`` page. An entry should consist of a small figure or icon and brief description, following the style of the existing entries.\n\n    * Figure should be added to the folder ``docs/source/community_gallery/figures``\n    * If you design the figure in PowerPoint then please add the source slide to the ``docs/source/community_gallery/figures/figure_icons_source.pptx`` file\n    * External links are typically defined as roles in the ``docs/source/conf_extlinks.py``\n\n**Step 2:** Build the docs and and review your changes via\n\n.. code-block::\n\n    cd docs\n    make html\n    open build/html/index.html\n\n**Step 3** Create a pull request to this repo with your changes\n\n\nExternal links\n==============\n\nAdding new external links\n-------------------------\n\nFor managing links to external resources we use the `extlinks \u003chttps://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html\u003e`_ of sphinx. The mapping of links is defined in the ``/docs/source/conf_extlinks.py`` as part of ``extlinks`` dictionary. To update or add a new link edit the ``extlinks`` dictionary. For example, ``extlinks`` includes the entry\n\n.. code-block:\n\n    extlinks = {\n        'incf_collection': ('https://training.incf.org/collection/neurodata-without-borders-neurophysiology-nwbn', ''),\n        'pynwb_issue': ('https://github.com/NeurodataWithoutBorders/pynwb/issues/%s', 'pynwb#%s')\n    }\n\nThe key in the dict defines the alias name as a new role so that we can write ``:pynwb_issue:`` to create a link. The value is the dict are a tuple consisting of the ``URL`` and the ``caption``.\n\n* **URL** The ``URL`` may contain ``%s`` once to extend the URL, e.g, in the case of linking to issues we need to add the issue number.\n* **Caption**:\n   * ``None`` : The the link caption rendered in the docs is the full URL\n   * ``''`` : The link caption in the text is the custom text indicated in the role\n   * ``text%s`` :  If the ``caption`` is a string, then it must contain ``%s`` exactly once. In this case the link caption is caption with the partial URL substituted for %s. E.g.,  in the above example, the link caption for pynwb issues would be issue pynwb#1.\n\nCreating external links in the docs\n-----------------------------------\n\nThe ``extlinks`` dict in ``/docs/source/conf_extlinks.py`` defines a set of new roles. This allows us to refer, e.g., to specific usses in PyNWB via ``:pynwb_issue:`1` `` which will in turn will be rendered as the text \"pynwb#1\" in the docs with the appropriate link to the issue. Similarly, if we want to refer to the INCF training we can write ``:incf_collection:`INCF Training` `` in the text. Since the caption is an empty string in the ``extlinks`` dict for the ``incf_collection`` key, the link will be rendered using the provided text, i.e., here \"INCF Training\" with the approbriate link.\n\nNormally the ``extlinks`` extension will add the part we link to the URL. To use the exact URL as defined in ``extlinks`` dict use the following syntax ``:pynwb-docs:`PyNWB \u003c\u003e` ``, which will render the text (here PyNWB) with a hyperlink to the exact, unmodified URL.\n\nLinking to external packages\n=============================\n\nAdding links to external packages\n---------------------------------\n\nTo link to specific entities (e.g., classes) in documentation of external software packages, we use the `intersphinx \u003chttps://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html\u003e`_ feature. The mapping to external docs is defined in ``/docs/source/conf_extlinks.py`` as part of the ``intersphinx_mapping`` dictionary. To support linking to a new tool, add the tool to the mapping.\n\nCreating external links to external packages in the docs\n--------------------------------------------------------\n\nOnce the mapping is defined, we can refer to specific types much like we would refer to classes in our own tools. For example, the intersphinx mapping includes mappings for ``PynNWB`` and ``Pandas``:\n\n.. code-block:: python\n\n    intersphinx_mapping = {\n        'pynwb': ('https://pynwb.readthedocs.io/en/stable/', None),\n        'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),\n    }\n\nWith this we can now easly link to elements in those packages. E.g., to links to the docs of ``pandas.DataFrame`` we would write ``:py:class:`~pandas.DataFrame` `` in the docs. Similarly, to link to ``NWBFile`` in ``PyNWB`` we would write ``:py:class:`~pynwb.file.NWBFile` `` in the docs. When including the ``~`` we tell Sphinx to ignore the package when rendering in the text, i.e., ``:py:class:`~pynwb.file.NWBFile` `` (with ``~``) will render as ``NWBFile`` in the docs, whereas ``:py:class:`pynwb.file.NWBFile` `` (without ``~``) will render as the full name ``pynwb.file.NWBFile``.\n\n\nNWB Software Analytics\n======================\n\nSoftware analytics are being managed via the `NWB Project Analytics \u003chttps://github.com/NeurodataWithoutBorders/nwb-project-analytics\u003e`_. This page checks out and renders the `nwb_project_analytics` automatically as part of the sphinx build process. The code statistics are being updated nightly via GitHub Actions on the `nwb_project_analytics` repository and are cached in the `data` folder of that repo. The rst sources and figures are then being generated automatically during the sphinx build.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneurodatawithoutborders%2Fnwb-overview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneurodatawithoutborders%2Fnwb-overview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneurodatawithoutborders%2Fnwb-overview/lists"}