documentation setup guide

documentation setup with live reload guide to help contribute to the ADS Public Documentation

Author: lyudmil-pelov

.gitignore

@@ -10,6 +10,8 @@ __pycache__/
 .Python
 env/
 build/
+docs/build/
+docs/docs_html/
 develop-eggs/
 dist/
 downloads/
@@ -24,6 +26,7 @@ wheels/
 *.egg-info/
 .installed.cfg
 *.egg
+ads_latest.zip
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

docs/README.md

@@ -0,0 +1,56 @@
+# Documentation
+
+## Getting Started
+
+Setup Conda.
+
+```bash
+curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -o Miniconda3-latest-Linux-x86_64.sh
+bash Miniconda3-latest-Linux-x86_64.sh
+```
+
+Create conda environment.
+
+```bash
+conda create -n ads-docs python=3.8
+conda activate ads-docs
+```
+
+Install relevant development packages.
+
+```bash
+pip install -r requirements.txt
+```
+
+## Developing Docs With Live Reload
+
+Start live-reload during the development face
+
+```bash
+sphinx-autobuild source/ build/
+```
+
+Open in the browser [http://127.0.0.1:8000]
+
+## Build
+
+To build and create the html documentation, run the following in the `docs/` folder.
+
+```bash
+sphinx-build -b html  source/ docs_html/ 
+```
+
+To `zip` the content of the html docs
+
+```bash
+zip -r ads-latest.zip docs_html/.  
+```
+
+## Notes
+
+- the `source/conf.py` defines most everything for the docs
+- the `ads.rst` was auto-generated but then hand edited to remove tests package
+
+## Contribute
+
+Now you can make updates to the docs and contributed via PRs.

docs/requirements.txt

@@ -1,8 +1,13 @@
--e .
 autodoc
 nbsphinx
 sphinx
 sphinxcontrib-napoleon
 sphinx-rtd-theme
+sphinx_copybutton
+oracle_ads
+sphinx-autobuild
+IPython
 pandoc
-sphinx-copybutton
+rstcheck
+restructuredtext_lint
+doc8

docs/source/conf.py

@@ -6,7 +6,8 @@
 import os
 import sys
 
-autoclass_content = "both"  ##This causes documentation within the __init__ method to be pulled into the documentation properly
+# This causes documentation within the __init__ method to be pulled into the documentation properly
+autoclass_content = "both"
 
 sys.path.insert(0, os.path.abspath("../../advanced-ds"))
 
@@ -30,7 +31,7 @@
     "sphinx.ext.graphviz",
     "sphinx.ext.inheritance_diagram",
     "nbsphinx",
-    "sphinx_copybutton",
+    "sphinx_copybutton"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -55,7 +56,8 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+# exclude_patterns = []
+exclude_patterns = ['build', '**.ipynb_checkpoints']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None