Merge pull request #165 from cta-observatory/update_docs

Update documentation with user and developer guide.

README.md

@@ -29,29 +29,8 @@ In general, *magic-cta-pipe* is still in heavy development phase, so expect larg
 
 # Instructions for developers
 
-People who would like to join the development of *magic-cta-pipe*, please contact Alessio Berti (<[email protected]>) to get write access to the repository.
-
-Developers should follow the coding style guidelines of the *ctapipe* project, see https://ctapipe.readthedocs.io/en/stable/developer-guide/style-guide.html and https://ctapipe.readthedocs.io/en/stable/developer-guide/code-guidelines.html.
-
-In short, to check for code/style errors and for reformatting the code:
-
-```
-pip install hacking     # installs all checker tools
-pip install black       # installs black formatter
-pyflakes magicctapipe   # checks for code errors
-flake8 magicctapipe     # checks style and code errors
-black filename.py       # reformats filename.py with black
-```
-
-The *black* and *isort* auto-formatters are used for automatic adherence to the code style. To enforce running these tools whenever you make a commit, setup the [pre-commit hook](https://pre-commit.com/):
-
-```bash
-$ pre-commit install
-```
-
-The pre-commit hook will then execute the tools with the same settings as when the a pull request is checked on github, and if any problems are reported the commit will be rejected. You then have to fix the reported issues before tying to commit again.
-
-In general, if you want to add a new feature or fix a bug, please open a new issue, and then create a new branch to develop the new feature or code the bug fix. You can create an early pull request even if it is not complete yet, you can tag it as "Draft" so that it will not be merged, and other developers can already check it and provide comments. When the code is ready, remove the tag "Draft" and select two people to review the pull request (at the moment the merge is not blocked if no review is performed, but that may change in the future). When the review is complete, the branch will be merged into the main branch.
+Developers should follow the development install instructions found in the
+[documentation](https://magic-cta-pipe.readthedocs.io/en/latest/developer-guide/getting-started.html).
 
 <!--
 A brief description:

docs/_static/magicctapipe.css

@@ -0,0 +1,67 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+    .wy-table-responsive table td {
+        /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+        white-space: normal !important;
+    }
+
+    .wy-table-responsive {
+        overflow: visible !important;
+    }
+}
+
+.version-switcher__container a[data-version-name*="stable"] {
+    background-color: #E9F6EC;
+    color: #28A745;
+}
+
+.version-switcher__container a[data-version-name*="dev"] {
+    background-color: #FDF4EB;
+    color: #EE9040;
+}
+
+html[data-theme="dark"] .version-switcher__container a[data-version-name*="stable"] {
+    background-color: #222924;
+    color: #28A745;
+}
+
+html[data-theme="dark"] .version-switcher__container a[data-version-name*="dev"] {
+    background-color: #332A21;
+    color: #EE9040;
+}
+
+
+/* sphinx-design */
+.sd-card {
+    border-radius: 5px;
+    padding: 30px 10px 20px 10px;
+    margin: 10px 0px;
+}
+
+.sd-card .sd-card-header .sd-card-text {
+    margin: 0px;
+}
+
+.sd-card .sd-card-header {
+    border: none;
+    text-align: center;
+    font-size: var(--pst-font-size-h4);
+    font-weight: bold;
+    padding: 0.5rem 0rem 0.5rem 0rem;
+}
+
+.sd-card .sd-card-footer {
+    border: none;
+}
+
+.sd-card .sd-card-footer .sd-card-text {
+    max-width: 220px;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+html[data-theme="dark"] .sd-shadow-sm {
+    --sd-color-shadow: #6e6e6e;
+}

docs/conf.py

@@ -13,6 +13,17 @@
 setup_metadata = dict(setup_cfg.items("metadata"))
 setup_options = dict(setup_cfg.items("options"))
 
+# -- General configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx_design",
+]
+
 # -- Project information
 
 project = setup_metadata["name"]
@@ -62,6 +73,7 @@
     # We want to keep the relative reference when on a pull request or locally
     json_url = "_static/switcher.json"
 
+# -- Options for HTML output
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -100,17 +112,17 @@
     "github_version": "master",
     "doc_path": "docs",
 }
+html_css_files = ["magicctapipe.css"]
+html_file_suffix = ".html"
 
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = f"{project} v{release}"
 
-# -- General configuration
+# Output file base name for HTML help builder.
+htmlhelp_basename = project + "doc"
 
-extensions = [
-    "sphinx.ext.duration",
-    "sphinx.ext.doctest",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.intersphinx",
-]
+html_theme = "pydata_sphinx_theme"
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
@@ -120,13 +132,5 @@
 
 templates_path = ["_templates"]
 
-# -- Options for HTML output
-
-html_theme = "pydata_sphinx_theme"
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-html_title = f"{project} v{release}"
-
 # -- Options for EPUB output
 epub_show_urls = "footnote"

docs/developer-guide/code-guidelines.rst

@@ -0,0 +1,7 @@
+.. _code_guidelines:
+
+Code Guidelines
+===============
+
+Coding should follow the CTA coding guidelines from the **CTA Code
+Standards** document. See the `ctapipe code guidelines <https://ctapipe.readthedocs.io/en/latest/developer-guide/code-guidelines.html>`_ for more information.