Adding documentation first version

LMMV · Sep 13, 2022 · 9e483fd · 9e483fd
1 parent 686b4a4
commit 9e483fd
Show file tree

Hide file tree

Showing 21 changed files with 237 additions and 19 deletions.
diff --git a/devtools/conda-envs/development_env.yaml b/devtools/conda-envs/development_env.yaml
@@ -18,4 +18,6 @@ dependencies:
 - sphinx_rtd_theme
 - sphinxcontrib-bibtex
 - myst-nb
+- sphinx-copybutton
+- sphinx-remove-toctrees
 - jupyterlab
diff --git a/devtools/conda-envs/docs_env.yaml b/devtools/conda-envs/docs_env.yaml
@@ -14,3 +14,5 @@ dependencies:
 - sphinx_rtd_theme
 - sphinxcontrib-bibtex
 - myst-nb
+- sphinx-copybutton
+- sphinx-remove-toctrees
diff --git a/devtools/requirements.yaml b/devtools/requirements.yaml
@@ -37,6 +37,8 @@ docs:
     - sphinx_rtd_theme
     - sphinxcontrib-bibtex
     - myst-nb
+    - sphinx-copybutton
+    - sphinx-remove-toctrees
 
 development:
   channels:

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,22 @@
+# Minimal makefile for Sphinx documentation
+#
+
+export SPHINXWORKING=True
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -j auto
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = openpocket
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/README.md b/docs/_static/README.md
@@ -0,0 +1,16 @@
+# Static Doc Directory
+
+Add any paths that contain custom static files (such as style sheets) here,
+relative to the `conf.py` file's directory. 
+They are copied after the builtin static files,
+so a file named "default.css" will overwrite the builtin "default.css".
+
+The path to this folder is set in the Sphinx `conf.py` file in the line: 
+```python
+templates_path = ['_static']
+```
+
+## Examples of file to add to this directory
+* Custom Cascading Style Sheets
+* Custom JavaScript code
+* Static logo images
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,10 @@
+.wy-nav-content {
+    max-width: 100% !important;
+}
+
+/* To change the left bar of executable cells in markdown and executable cells in jupyter notebooks */
+/* See https://github.com/executablebooks/meta/discussions/667 */
+div.cell div.cell_input {
+    border-left-color: #C9C9C9;
+}
+
diff --git a/docs/_templates/README.md b/docs/_templates/README.md
@@ -0,0 +1,14 @@
+# Templates Doc Directory
+
+Add any paths that contain templates here, relative to  
+the `conf.py` file's directory.
+They are copied after the builtin template files,
+so a file named "page.html" will overwrite the builtin "page.html".
+
+The path to this folder is set in the Sphinx `conf.py` file in the line: 
+```python
+html_static_path = ['_templates']
+```
+
+## Examples of file to add to this directory
+* HTML extensions of stock pages like `page.html` or `layout.html`
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -0,0 +1,8 @@
+{% extends '!layout.html' %}
+{% block document %}
+{{super()}}
+    <a href="https://github.com/uibcdf/openpocket">
+        <img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub">
+    </a>
+{% endblock %}
+
diff --git a/docs/api/developers/api_developers.rst b/docs/api/developers/api_developers.rst
@@ -0,0 +1,8 @@
+Developers
+==========
+
+.. toctree::
+   :name: developers
+   :caption: Developers
+   :maxdepth: 2
+
diff --git a/docs/api/users/api_users.rst b/docs/api/users/api_users.rst
@@ -0,0 +1,8 @@
+Users
+=====
+
+.. toctree::
+   :name: users
+   :caption: Users
+   :maxdepth: 2
+
diff --git a/docs/conf.py b/docs/conf.py
@@ -173,7 +173,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'molsysmtdoc'
+htmlhelp_basename = 'openpocketdoc'
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -200,8 +200,6 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'molsysmt.tex', 'MolSysMT Documentation',
-     'molsysmt', 'manual'),
 ]
 
 
@@ -210,8 +208,6 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'molsysmt', 'MolSysMT Documentation',
-     [author], 1)
 ]
 
 
@@ -221,9 +217,6 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'molsysmt', 'MolSysMT Documentation',
-     author, 'molsysmt', 'One line description of project.',
-     'Miscellaneous'),
 ]
 
 

diff --git a/docs/contents/about/citation.md b/docs/contents/about/citation.md
@@ -0,0 +1,3 @@
+# Citation
+
+To be written soon...
diff --git a/docs/contents/about/installation.md b/docs/contents/about/installation.md
@@ -0,0 +1,3 @@
+# Installation
+
+To be written soon...
diff --git a/docs/contents/about/showcase/index.md b/docs/contents/about/showcase/index.md
@@ -0,0 +1,3 @@
+# Showcase
+
+To be written soon...
diff --git a/docs/contents/about/what.md b/docs/contents/about/what.md
@@ -0,0 +1,3 @@
+# What
+
+To be written soon...
diff --git a/docs/contents/developer/intro/index.md b/docs/contents/developer/intro/index.md
@@ -0,0 +1 @@
+# Introduction
diff --git a/docs/contents/user/intro/index.md b/docs/contents/user/intro/index.md
@@ -0,0 +1 @@
+# Introduction
diff --git a/docs/contents/user/tools/index.md b/docs/contents/user/tools/index.md
@@ -0,0 +1 @@
+# Tools
diff --git a/docs/index.ipynb b/docs/index.ipynb
@@ -0,0 +1,118 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "6c9de210-0ac6-4ee9-9dad-7cfe0b988806",
+   "metadata": {},
+   "source": [
+    "# OpenPocket\n",
+    "\n",
+    "```{image} https://anaconda.org/uibcdf/openpocket/badges/license.svg\n",
+    ":target: https://github.com/uibcdf/OpenPocket/blob/master/License\n",
+    "```\n",
+    "\n",
+    "OpenPocket makes the characterization of molecular surfaces easy.\n",
+    "\n",
+    "## Install it\n",
+    "\n",
+    "```bash\n",
+    "conda install -c uibcdf openpocket\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8892c794-5ead-4dff-8035-22123b57761f",
+   "metadata": {},
+   "source": [
+    "## Use it"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0219ddce-3929-4ed8-bec1-46390da25f93",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import openpocket as opoc"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "73eaeea9-8117-4d12-a436-36736567322b",
+   "metadata": {},
+   "source": [
+    "## Citation\n",
+    "\n",
+    "Coming soon..."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "96727aaf-6fb1-4929-9dc5-d51fc8ff3cd0",
+   "metadata": {},
+   "source": [
+    "```{eval-rst}\n",
+    ".. toctree::\n",
+    "   :name: about\n",
+    "   :caption: About\n",
+    "   :maxdepth: 2\n",
+    "   :hidden:\n",
+    "\n",
+    "   contents/about/what.md\n",
+    "   contents/about/installation.md\n",
+    "   contents/about/showcase/index.md\n",
+    "   contents/about/citation.md\n",
+    "\n",
+    ".. toctree::\n",
+    "   :name: user_guide\n",
+    "   :caption: User Guide\n",
+    "   :maxdepth: 2\n",
+    "   :hidden:\n",
+    "\n",
+    "   contents/user/intro/index.md\n",
+    "   contents/user/tools/index.md\n",
+    "\n",
+    ".. toctree::\n",
+    "   :name: developer_guide\n",
+    "   :caption: Developer Guide\n",
+    "   :maxdepth: 2\n",
+    "   :hidden:\n",
+    "\n",
+    "   contents/developer/intro/index.md\n",
+    "   \n",
+    ".. toctree::\n",
+    "   :name: api_doc\n",
+    "   :caption: API Documentation\n",
+    "   :maxdepth: 2\n",
+    "   :hidden:\n",
+    "\n",
+    "   api/users/api_users.rst\n",
+    "   api/developers/api_developers.rst\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/contents/alpha_spheres_1.ipynb → sandbox/alpha_spheres_1.ipynb b/docs/contents/alpha_spheres_1.ipynb → sandbox/alpha_spheres_1.ipynb
@@ -362,7 +362,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "6657e628892f40978108ada30bd093fd",
+       "model_id": "7c3daa1acfb04985967f6ea1bd9eb544",
        "version_major": 2,
        "version_minor": 0
       },
@@ -374,7 +374,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "d8b257729e0b4fbf96556016784261da",
+       "model_id": "693cb2bf6b5a40c19a1f846970b0edff",
        "version_major": 2,
        "version_minor": 0
       },

diff --git a/docs/contents/alpha_spheres_2.ipynb → sandbox/alpha_spheres_2.ipynb b/docs/contents/alpha_spheres_2.ipynb → sandbox/alpha_spheres_2.ipynb
@@ -37,7 +37,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "160a1b3639824055b7c37acbe3fe8601",
+       "model_id": "7e57cd1fb5a34ccf8f6b0488afbd7192",
        "version_major": 2,
        "version_minor": 0
       },
@@ -71,9 +71,9 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "/home/diego/MyMachine/locals/miniconda3/envs/OpenPocket@dprada_3.9/lib/python3.9/site-packages/molsysmt/item/mmtf_MMTFDecoder/to_molsysmt_Topology.py:32: UserWarning: The structure in the PDB has biological assemblies. There are geometrical transformations proposed in the structure. See the following issue in the source code repository: https://github.com/uibcdf/MolSysMT/issues/33\n",
+      "/home/diego/Myopt/miniconda3/envs/OpenPocket@dprada_3.9/lib/python3.9/site-packages/molsysmt/item/mmtf_MMTFDecoder/to_molsysmt_Topology.py:32: UserWarning: The structure in the PDB has biological assemblies. There are geometrical transformations proposed in the structure. See the following issue in the source code repository: https://github.com/uibcdf/MolSysMT/issues/33\n",
       "  warnings.warn(warning_message)\n",
-      "/home/diego/MyMachine/locals/miniconda3/envs/OpenPocket@dprada_3.9/lib/python3.9/site-packages/molsysmt/item/mmtf_MMTFDecoder/to_molsysmt_Topology.py:32: UserWarning: The structure in the PDB has biological assemblies. There are geometrical transformations proposed in the structure. See the following issue in the source code repository: https://github.com/uibcdf/MolSysMT/issues/33\n",
+      "/home/diego/Myopt/miniconda3/envs/OpenPocket@dprada_3.9/lib/python3.9/site-packages/molsysmt/item/mmtf_MMTFDecoder/to_molsysmt_Topology.py:32: UserWarning: The structure in the PDB has biological assemblies. There are geometrical transformations proposed in the structure. See the following issue in the source code repository: https://github.com/uibcdf/MolSysMT/issues/33\n",
       "  warnings.warn(warning_message)\n"
      ]
     }
@@ -99,7 +99,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "300bb650defc40629a58e461178e6e4e",
+       "model_id": "85478b47419042e39f5fb56ef0014ba9",
        "version_major": 2,
        "version_minor": 0
       },
@@ -2049,7 +2049,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 10,
    "id": "c2d79f50-6592-48e8-9f41-c4a59daf3f54",
    "metadata": {},
    "outputs": [
@@ -2059,7 +2059,7 @@
        "(1822, 3)"
       ]
      },
-     "execution_count": 11,
+     "execution_count": 10,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -2078,7 +2078,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 11,
    "id": "1c85d15b-0991-473c-8bb1-4b476260cbb2",
    "metadata": {},
    "outputs": [],
@@ -2088,7 +2088,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 12,
    "id": "551620cd-3dc1-4170-8c05-a516243219a0",
    "metadata": {},
    "outputs": [
@@ -2098,7 +2098,7 @@
        "11834"
       ]
      },
-     "execution_count": 13,
+     "execution_count": 12,
      "metadata": {},
      "output_type": "execute_result"
     }