diff --git a/docs/.DS_Store b/docs/.DS_Store index 314cd81..272df93 100644 Binary files a/docs/.DS_Store and b/docs/.DS_Store differ diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 86385a5..e2eb084 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -33,3 +33,8 @@ html[data-theme="light"] { html[data-theme="dark"] { --pst-color-primary: rgb(0, 174, 255); } + +/* The default font size is fairly small, so this increases it */ +body { + font-size: 1.3em +} diff --git a/docs/conf.py b/docs/conf.py index 54f1778..a07fc43 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,8 +31,9 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - # githubpages just adds a .nojekyll file - "sphinx.ext.githubpages", + "sphinx.ext.githubpages", # used for hosting on GitHub Pages + "sphinx.ext.todo", + "sphinx_copybutton", # adds a copy button to source code blocks "sphinx_design" ] @@ -85,6 +86,7 @@ 'css/custom.css' ] +todo_include_todos = True # HTML context: from os.path import basename, dirname, realpath diff --git a/docs/guides/.DS_Store b/docs/guides/.DS_Store new file mode 100644 index 0000000..b72a5c8 Binary files /dev/null and b/docs/guides/.DS_Store differ diff --git a/docs/guides/guide_installation.rst b/docs/guides/guide_installation.rst index 7a74cfb..a649577 100644 --- a/docs/guides/guide_installation.rst +++ b/docs/guides/guide_installation.rst @@ -1,4 +1,73 @@ -Installation -============ +Installing Sphinx +================= -This is a subject \ No newline at end of file + +Local Installation +================== + +.. tip:: + When you need to write a lot of documentation, it's a **good idea** to do it all locally. + + +1. Cloning the Repo +------------------------ +Clone the `sphinx-documentation-demo `_ GitHub repository into a local directory: + +.. code-block:: bash + + git clone git@github.com:bioteam/sphinx-documentation-demo.git + +2. Installing Sphinx +--------------------------------- +Sphinx, and extensions for Sphinx, are *python packages* that can be installed on your computer. +The packages you need to install are in :code:`requirements.txt` in the :code:`sphinx-documentation-demo` repository. +It's a good idea to install them in a **virtual environment**. + + + +2a. Using :code:`venv` to install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + python -m venv sphinx_venv + source sphinx_venv/bin/activate + pip install -r requirements.txt + + + +3. Building Documentation +------------------------- +The documentation for the :code:`sphinx-documentation-demo` is located in :code:`docs/`. +To build this documentation, while in the project directory, do: + +.. code-block:: bash + + sphinx-build -M html docs/ _build + +This will tell Sphinx to generate static HTML documentation from :term:`rST` files within :code:`docs/` and then place them in :code:`_build`. +You can open the file :code:`docs/index.html` on your computer to view the HTML documentation in your web browser. + + + +3a. Using :code:`sphinx-autobuild` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The :code:`sphinx-autobuild` extension allows us to build local documentation whenever we make changes. +It also refreshes the web browser so you can see the changes "live". This makes it **very convenient for rapid development**. + +This extension has already been included in the :code:`requirements.txt` file + +While in the virtual environment, run the following command: + +.. code-block:: bash + + sphinx-autobuild docs _build + +This will create a local host instance which you can then access through your web browser (you can just copy/paste the http address you get from :code:`sphinx-autobuild`) + +Remote Build on GitHub +====================== + +.. todo:: + + Finish the guide for remote building on GitHub. \ No newline at end of file diff --git a/docs/guides/guide_what_is_sphinx.rst b/docs/guides/guide_what_is_sphinx.rst new file mode 100644 index 0000000..7b1412d --- /dev/null +++ b/docs/guides/guide_what_is_sphinx.rst @@ -0,0 +1,65 @@ +What is Sphinx? +=============== + +Sphinx lets you generate static web pages that can be hosted on sites such as `Github Pages `_ and `Read the Docs `_. +While there are other tools that can be used to generate documentation, Sphinx is **open source**, popular, and well-supported. + +Some use cases for Sphinx include: + + +.. grid:: 2 + :gutter: 4 + + .. grid-item-card:: + :class-header: `sd-bg-secondary sd-text-white sd-text-center` + + :material-regular:`dvr;2em` Documenting Code + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Sphinx can be used to generate documentation from `docstrings `_. For example: Python's `code documentation `_. + + + .. grid-item-card:: + :class-header: `sd-bg-secondary sd-text-white sd-text-center` + + :material-regular:`auto_stories;2em` Knowledge Base + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Sphinx can also be used more like a wiki, where reference documents can be hosted in an accessible location. + + .. grid-item-card:: + :class-header: `sd-bg-secondary sd-text-white sd-text-center` + + :material-regular:`rss_feed;2em` Blogging + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + "Blog-style" posts can be integrated into any Sphinx project using the `ABlog extension `_. + + .. grid-item-card:: + :class-header: `sd-bg-secondary sd-text-white sd-text-center` + + :material-regular:`visibility;2em` Data Visualization + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Jupyter notebook visualizations can be embedded into Sphinx documentation using the `nbsphinx `_ extension. + + .. grid-item-card:: + :margin: 4 2 auto auto + :class-header: `sd-bg-secondary sd-text-white sd-text-center` + :text-align: center + + :material-regular:`image;2em` Gallery + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + You can easily throw together a gallery of cards to highlight important features, links, or images. For example, `this site `_. + +How do I use Sphinx? +==================== +.. admonition:: Why reStructuredText (rST)? + :class: sidebar note + + This demo assumes you'll be using rST to write documentation. + While there is `support for Markdown `_, the grammar can be cumbersome when writing complicated :term:`directives`. + +Sphinx can be run locally on your laptop to generate HTML files from source code, `Markdown `_, or `reStructredText (rST) `_. +You can also run it remotely on GitHub by adding a post-commit hook to build documentation pushed to a repository. This will be expanded upon in a later tutorial. + +.. todo:: + + Add link to tutorial to build docs in GitHub + diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 5702e66..7104a75 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -6,13 +6,17 @@ Guides :maxdepth: 1 :caption: Starting Out + guide_what_is_sphinx guide_installation + layout/index .. toctree:: :maxdepth: 1 :caption: References reference_directives + reference_glossary + reference_todo .. toctree:: :maxdepth: 1 diff --git a/docs/guides/layout/.DS_Store b/docs/guides/layout/.DS_Store new file mode 100644 index 0000000..745a7ba Binary files /dev/null and b/docs/guides/layout/.DS_Store differ diff --git a/docs/guides/layout/images/.DS_Store b/docs/guides/layout/images/.DS_Store new file mode 100644 index 0000000..54155c0 Binary files /dev/null and b/docs/guides/layout/images/.DS_Store differ diff --git a/docs/guides/layout/images/layout_left.png b/docs/guides/layout/images/layout_left.png new file mode 100644 index 0000000..dc28d8f Binary files /dev/null and b/docs/guides/layout/images/layout_left.png differ diff --git a/docs/guides/layout/images/layout_overview.png b/docs/guides/layout/images/layout_overview.png new file mode 100644 index 0000000..acfbb21 Binary files /dev/null and b/docs/guides/layout/images/layout_overview.png differ diff --git a/docs/guides/layout/images/layout_right.png b/docs/guides/layout/images/layout_right.png new file mode 100644 index 0000000..1b62388 Binary files /dev/null and b/docs/guides/layout/images/layout_right.png differ diff --git a/docs/guides/layout/images/layout_top.png b/docs/guides/layout/images/layout_top.png new file mode 100644 index 0000000..4adc704 Binary files /dev/null and b/docs/guides/layout/images/layout_top.png differ diff --git a/docs/guides/layout/images/logo_loc.png b/docs/guides/layout/images/logo_loc.png new file mode 100644 index 0000000..03bf229 Binary files /dev/null and b/docs/guides/layout/images/logo_loc.png differ diff --git a/docs/guides/layout/images/tab2_top.png b/docs/guides/layout/images/tab2_top.png new file mode 100644 index 0000000..0b2d27f Binary files /dev/null and b/docs/guides/layout/images/tab2_top.png differ diff --git a/docs/guides/layout/images/tabs.png b/docs/guides/layout/images/tabs.png new file mode 100644 index 0000000..95bf94f Binary files /dev/null and b/docs/guides/layout/images/tabs.png differ diff --git a/docs/guides/layout/images/top_bar.png b/docs/guides/layout/images/top_bar.png new file mode 100644 index 0000000..32dc47a Binary files /dev/null and b/docs/guides/layout/images/top_bar.png differ diff --git a/docs/guides/layout/index.rst b/docs/guides/layout/index.rst new file mode 100644 index 0000000..d3c2e36 --- /dev/null +++ b/docs/guides/layout/index.rst @@ -0,0 +1,7 @@ +Documentation Layout +==================== + +.. toctree:: + :maxdepth: 1 + + layout_basic diff --git a/docs/guides/layout/layout_basic.rst b/docs/guides/layout/layout_basic.rst new file mode 100644 index 0000000..659892f --- /dev/null +++ b/docs/guides/layout/layout_basic.rst @@ -0,0 +1,120 @@ +Layout Overview +============================= +.. note:: + :class: sidebar + + The Sphinx theme (`PyData `_ in our case) can also affect how documents are shown in the layout. + +The documentation you see on this website is built from the `docs `_ directory located in the project. + +Sphinx compiles the :term:`rST` files inside of this directory and generates static HTML files. +The file layout of the :code:`docs/` directory, along with "toctrees" (which we will cover this later), will **determine the website layout of the documentation**. + +Therefore it's important to understand how to organize files within the :code:`docs/` directory so that Sphinx knows where to display them. +We'll cover this over the course of several short tutorials so that you can learn how to: + +.. + .. list-table:: + :header-rows: 1 + + * - **Add a new...** + * - Tab to the top navigation bar + * - Page to the left navigation bar + * - Section to the left navigation bar + +* Add a new tab to the top navigation bar +* Add a new page to the left navigation bar +* Add a new section to the left navigation bar + +Before that, we review each of the major layout components in the sections below. + +Top Navigation Bar +================== + +.. figure:: images/layout_top.png + :class: sd-border-2 + + The top navigation bar (highlighted in red) + + +Logo +---- + +The "logo" is located in the upper-left-hand corner of the page. +Typically this is just text, but you can also add an icon. +To change the text that you see: + +1. Go into :code:`docs/conf.py` +2. In html_theme_options... +3. Change the text stored in the "logo" key: + +.. image:: images/logo_loc.png + :class: sd-border-2 + + + +.. seealso:: + + `PyData's guide on changing the logo `_ + + + +Tabs +---- +.. figure:: images/tabs.png + :class: sd-border-2 + + This project has three tabs, although two of them are for demonstration purposes. + + + +You can organize content into different "tabs". +For example, a code project could be partitioned into a "Tutorials" tab (for in-depth documentation) and an "API" tab (for documenting specific functions) + +A tab is created for each "toctree" in the root index file :code:`docs/index.rst`. +This will be covered in a later tutorial. + +.. todo:: + + Link to the tabs tutorial + + +Search Bar +---------- +.. warning:: + :class: sidebar + + The search bar doesn't work well when you are viewing documentation **locally** on your computer. + +Sphinx comes with built-in search functionality. +Users that enter text into the search bar in the upper-right-hand corner can search across multiple documentation pages. + +Left Navigation Bar +=================== +.. figure:: images/layout_left.png + :class: sd-border-2 + + The left navigation bar (highlighted in red) + + +The left navigation bar allows users to navigate between documents that have been indexed within a "toctree" (more on this later). +Each tab will have its own left navigation bar, allowing you to organize :term:`rST` files into one "folder" per tab. + +Right Navigation Bar +=================== +.. figure:: images/layout_right.png + :class: sd-border-2 + + The right navigation bar (highlighted in red) + + +The right navigation bar allows users to navigation between **different sections within the current page**. +This is automatically generated based on section headers specified within the page's :term:'rST' file. + +.. + .. image:: images/tab2_top.png + :class: sd-border-2 + + | + + diff --git a/docs/guides/reference_glossary.rst b/docs/guides/reference_glossary.rst new file mode 100644 index 0000000..7b49d87 --- /dev/null +++ b/docs/guides/reference_glossary.rst @@ -0,0 +1,29 @@ +Glossary +======== + +.. Glossary:: + + Directive + Directives are special commands that can be embedded as text into an rST document. + They can be used to dictate how content in the document gets formatted by Sphinx. + + For example, having this in a document: + + .. code-block:: rst + + .. admonition:: title + + content + + ... would generate this: + + .. admonition:: title + + content + + + rST + reStructuredText is a plaintext markup language that Sphinx can use to generate documentation. + This will be the standard way we write documentation in this project. Mardown is an alternative langauge. + + See this `cheat sheet `_ for the common markup used in rST files. diff --git a/docs/guides/reference_todo.rst b/docs/guides/reference_todo.rst new file mode 100644 index 0000000..337e1af --- /dev/null +++ b/docs/guides/reference_todo.rst @@ -0,0 +1,7 @@ +Todo List +================= + +This will generate a list of todo entries when todo_include_todos is set to "True" in config.py + + +.. todolist:: diff --git a/docs/tab_2/subject_1.rst b/docs/tab_2/subject_1.rst index f81c06f..7605181 100644 --- a/docs/tab_2/subject_1.rst +++ b/docs/tab_2/subject_1.rst @@ -1,4 +1,29 @@ Subject_1 ========== -This is a subject \ No newline at end of file +This is a long page to test out some of the features of Sphinx. + + +Section 1 +========= + +Subsection 1 +------------ + +Sub-Subsection 1 +~~~~~~~~~~~~~~~~ + +Sub-Subsection 2 +~~~~~~~~~~~~~~~~ + +Sub-Subsection 3 +~~~~~~~~~~~~~~~~ + +Subsection 2 +------------ + +Section 2 +============ + +Subsection 3 +------------