From ac73a170c63379c501d47b2eaed43c0f72e49b85 Mon Sep 17 00:00:00 2001
From: Adriaan de Beer <adriaan@spaceadvisory.com>
Date: Tue, 5 Nov 2019 10:51:31 +0200
Subject: [PATCH 1/4] started implementing some automatic docstrings with
 extremely simplistic usage of sphinx directives

---
 docs/src/conf.py                           |  7 ++++---
 docs/src/index.rst                         |  5 ++---
 docs/src/package/guide.rst                 | 15 +++++++++++++++
 ska_python_skeleton/main.py                | 20 ++++++++++++++++++++
 ska_python_skeleton/ska_python_skeleton.py | 13 -------------
 tests/test_ska_skeleton.py                 |  6 +++---
 6 files changed, 44 insertions(+), 22 deletions(-)
 create mode 100644 ska_python_skeleton/main.py
 delete mode 100644 ska_python_skeleton/ska_python_skeleton.py

diff --git a/docs/src/conf.py b/docs/src/conf.py
index 3350dca..84b7559 100644
--- a/docs/src/conf.py
+++ b/docs/src/conf.py
@@ -17,9 +17,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
 import sphinx_rtd_theme
 
 def setup(app):
@@ -36,6 +36,7 @@ def setup(app):
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.napoleon',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
diff --git a/docs/src/index.rst b/docs/src/index.rst
index d10b376..459e689 100644
--- a/docs/src/index.rst
+++ b/docs/src/index.rst
@@ -26,10 +26,9 @@
   package/guide
 
 
-
-Package-name documentation
+Project-name documentation
 ==========================
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+These are all the packages, functions and scripts that form part of the project.
 
 - :doc:`package/guide`
diff --git a/docs/src/package/guide.rst b/docs/src/package/guide.rst
index 17b0e69..3677c1c 100644
--- a/docs/src/package/guide.rst
+++ b/docs/src/package/guide.rst
@@ -14,3 +14,18 @@ Subtitle
 ========
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+Public API Documentation
+````````````````````````
+
+Functions
+---------
+
+.. automodule:: ska_python_skeleton.main
+    :members:
+
+Classes
+-------
+.. autoclass:: ska_python_skeleton.main.SKA
+    :noindex:
+    :members:
diff --git a/ska_python_skeleton/main.py b/ska_python_skeleton/main.py
new file mode 100644
index 0000000..3a106ce
--- /dev/null
+++ b/ska_python_skeleton/main.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+
+#"""Define function placeholders and test function examples."""
+
+
+# TODO: Replace all the following code with the desired functionality for the package
+def function_example():
+    """Example: function outside of a class"""
+
+
+# TODO: Replace all the following code with the desired functionality for the package
+class SKA():
+    """Define class and it's attributes"""
+
+    def example(self):
+        """Example: Define non return function for subsequent test."""
+
+    def testing_example(self):
+        """Example: Define function for subsequent test with specific return value."""
+        return 2
diff --git a/ska_python_skeleton/ska_python_skeleton.py b/ska_python_skeleton/ska_python_skeleton.py
deleted file mode 100644
index 6a6f6e5..0000000
--- a/ska_python_skeleton/ska_python_skeleton.py
+++ /dev/null
@@ -1,13 +0,0 @@
-# -*- coding: utf-8 -*-
-
-"""Define function placeholders and test function examples."""
-
-
-# TODO: Replace all the following code with the desired functionality for the package
-def example():
-    """Example: Define non return function for subsequent test."""
-
-
-def testing_example():
-    """Example: Define function for subsequent test with specific return value."""
-    return 2
diff --git a/tests/test_ska_skeleton.py b/tests/test_ska_skeleton.py
index 4d526b1..77b92f9 100644
--- a/tests/test_ska_skeleton.py
+++ b/tests/test_ska_skeleton.py
@@ -4,7 +4,7 @@
 """Tests for the ska_python_skeleton module."""
 import pytest
 
-from ska_python_skeleton import ska_python_skeleton
+from ska_python_skeleton import main
 
 
 # TODO: Replace all the following examples with tests for the ska_python_skeleton package code
@@ -34,5 +34,5 @@ def test_ska_python_skeleton(an_object):
 
 def test_package():
     """Example: Assert the ska_python_skeleton package code."""
-    assert ska_python_skeleton.example() is None
-    assert ska_python_skeleton.testing_example() == 2
+    assert main.example() is None
+    assert main.testing_example() == 2
-- 
GitLab


From 538286c008b7e5704cb53f397d735510d62c7ef3 Mon Sep 17 00:00:00 2001
From: Adriaan de Beer <adriaan@spaceadvisory.com>
Date: Tue, 5 Nov 2019 11:10:11 +0200
Subject: [PATCH 2/4] simple comment added

---
 docs/src/package/guide.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/src/package/guide.rst b/docs/src/package/guide.rst
index 3677c1c..de41a69 100644
--- a/docs/src/package/guide.rst
+++ b/docs/src/package/guide.rst
@@ -15,9 +15,10 @@ Subtitle
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
+.. Automatic API Documentation section. Generating the API from the docstrings. Modify / change the directory structure as you like
+
 Public API Documentation
 ````````````````````````
-
 Functions
 ---------
 
-- 
GitLab


From 9f9763ca6b6f0e70208452cdfa04565be20ab020 Mon Sep 17 00:00:00 2001
From: Adriaan de Beer <adriaan@spaceadvisory.com>
Date: Tue, 5 Nov 2019 15:47:24 +0200
Subject: [PATCH 3/4] fixed tests

---
 ska_python_skeleton/{main.py => ska_python_skeleton.py} | 8 +++++---
 tests/test_ska_skeleton.py                              | 8 +++++---
 2 files changed, 10 insertions(+), 6 deletions(-)
 rename ska_python_skeleton/{main.py => ska_python_skeleton.py} (85%)

diff --git a/ska_python_skeleton/main.py b/ska_python_skeleton/ska_python_skeleton.py
similarity index 85%
rename from ska_python_skeleton/main.py
rename to ska_python_skeleton/ska_python_skeleton.py
index 3a106ce..7dd613e 100644
--- a/ska_python_skeleton/main.py
+++ b/ska_python_skeleton/ska_python_skeleton.py
@@ -9,12 +9,14 @@ def function_example():
 
 
 # TODO: Replace all the following code with the desired functionality for the package
-class SKA():
-    """Define class and it's attributes"""
+class SKA:
+    """Define class, methods etc"""
+
+    something = 0
 
     def example(self):
         """Example: Define non return function for subsequent test."""
 
-    def testing_example(self):
+    def example_2(self):
         """Example: Define function for subsequent test with specific return value."""
         return 2
diff --git a/tests/test_ska_skeleton.py b/tests/test_ska_skeleton.py
index 77b92f9..553d179 100644
--- a/tests/test_ska_skeleton.py
+++ b/tests/test_ska_skeleton.py
@@ -4,7 +4,7 @@
 """Tests for the ska_python_skeleton module."""
 import pytest
 
-from ska_python_skeleton import main
+from ska_python_skeleton import ska_python_skeleton
 
 
 # TODO: Replace all the following examples with tests for the ska_python_skeleton package code
@@ -34,5 +34,7 @@ def test_ska_python_skeleton(an_object):
 
 def test_package():
     """Example: Assert the ska_python_skeleton package code."""
-    assert main.example() is None
-    assert main.testing_example() == 2
+    assert ska_python_skeleton.function_example() is None
+    foo = ska_python_skeleton.SKA()
+    assert foo.example_2() == 2
+    assert foo.example() is None
-- 
GitLab


From 5e70fde37b09fe5f7c14fd94511dd09b5b463d28 Mon Sep 17 00:00:00 2001
From: Adriaan de Beer <adriaan@spaceadvisory.com>
Date: Tue, 12 Nov 2019 17:13:57 +0200
Subject: [PATCH 4/4] Include README.md as optional documentation of the
 project

---
 Pipfile                    |  1 +
 README.md                  |  7 ++++++-
 docs/Makefile              |  2 ++
 docs/src/README.md         |  1 +
 docs/src/conf.py           |  7 ++++---
 docs/src/index.rst         | 16 +++++++++++++---
 docs/src/package/guide.rst |  4 ++--
 7 files changed, 29 insertions(+), 9 deletions(-)
 create mode 120000 docs/src/README.md

diff --git a/Pipfile b/Pipfile
index dc64316..13f0fad 100644
--- a/Pipfile
+++ b/Pipfile
@@ -23,6 +23,7 @@ Sphinx = "*"
 sphinx_rtd_theme = "*"
 sphinx-autobuild = "*"
 sphinxcontrib-websupport = "*"
+recommonmark = "*"
 
 [dev-packages]
 
diff --git a/README.md b/README.md
index 2cf4aab..fb51625 100644
--- a/README.md
+++ b/README.md
@@ -66,8 +66,13 @@ Writing documentation
  --------------------
  * The documentation generator for this project is derived from SKA's [SKA Developer Portal repository](https://github.com/ska-telescope/developer.skatelescope.org)
  * The documentation can be edited under `./docs/src`
+ * If you want to include only your README.md file, create a symbolic link inside the `./docs/src` directory if the existing one does not work:
+ ```bash
+$ cd docs/src
+$ ln -s ../../README.md README.md
+```
  * In order to build the documentation for this specific project, execute the following under `./docs`:
  ```bash
-> make html
+$ make html
 ```
 * The documentation can then be consulted by opening the file `./docs/build/html/index.html`
diff --git a/docs/Makefile b/docs/Makefile
index 4164814..d8667e3 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,3 +1,4 @@
+SHELL := /bin/bash
 # Minimal makefile for Sphinx documentation
 #
 
@@ -18,3 +19,4 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
diff --git a/docs/src/README.md b/docs/src/README.md
new file mode 120000
index 0000000..fe84005
--- /dev/null
+++ b/docs/src/README.md
@@ -0,0 +1 @@
+../../README.md
\ No newline at end of file
diff --git a/docs/src/conf.py b/docs/src/conf.py
index 84b7559..8ee1cc5 100644
--- a/docs/src/conf.py
+++ b/docs/src/conf.py
@@ -44,7 +44,8 @@ extensions = ['sphinx.ext.autodoc',
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages']
+    'sphinx.ext.githubpages',
+              'recommonmark']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -52,8 +53,8 @@ templates_path = ['_templates']
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
diff --git a/docs/src/index.rst b/docs/src/index.rst
index 459e689..3443f7b 100644
--- a/docs/src/index.rst
+++ b/docs/src/index.rst
@@ -9,17 +9,27 @@
 .. Hidden toctree to manage the sidebar navigation.
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
   :caption: Home
   :hidden:
 
 
+.. README =============================================================
+
+.. This project most likely has it's own README. We include it here.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Readme
+
+   README
+
 .. COMMUNITY SECTION ==================================================
 
-.. Hidden toctree to manage the sidebar navigation.
+..
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
   :caption: Package-name
   :hidden:
 
diff --git a/docs/src/package/guide.rst b/docs/src/package/guide.rst
index de41a69..9b3c93e 100644
--- a/docs/src/package/guide.rst
+++ b/docs/src/package/guide.rst
@@ -22,11 +22,11 @@ Public API Documentation
 Functions
 ---------
 
-.. automodule:: ska_python_skeleton.main
+.. automodule:: ska_python_skeleton.ska_python_skeleton
     :members:
 
 Classes
 -------
-.. autoclass:: ska_python_skeleton.main.SKA
+.. autoclass:: ska_python_skeleton.ska_python_skeleton.SKA
     :noindex:
     :members:
-- 
GitLab