Repository: MycroftAI/mycroft-core

Issue:
MycroftSkill Autodoc documentation does not include important class instance variables
The auto-generated skills API documentation found at [readthedocs.io](http://mycroft-core.readthedocs.io/en/stable/source/mycroft.html#mycroftskill-class) contains methods, but seems to omit important variables.

"For module data members and class attributes, documentation can either be put into a comment with special formatting (using a #: to start the comment instead of just #), or in a docstring after the definition. Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line." 
from [Include documentation from docstrings, Sphinix-doc.org](http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-autoattribute) 

For example the file_system variable as seen here:
http://mycroft-core.readthedocs.io/en/stable/_modules/mycroft/skills/core.html?highlight=file_system

should be preceded by this:
#:file_system is the path to the skill installation directory. Available for general Read-Write access.

and the autodoc generation re-run.



Discussion:

Resolving patch:
diff --git a/doc/conf.py b/doc/conf.py
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -22,6 +22,16 @@
 import re
 import os
 
+import sphinx_rtd_theme
+from sphinx.ext.autodoc import (
+    ClassLevelDocumenter, InstanceAttributeDocumenter)
+
+
+def iad_add_directive_header(self, sig):
+    ClassLevelDocumenter.add_directive_header(self, sig)
+
+
+InstanceAttributeDocumenter.add_directive_header = iad_add_directive_header
 
 sys.path.insert(0, os.path.abspath('../'))
 
@@ -43,7 +53,7 @@
                                flags=re.MULTILINE))
 
 # Dependencies with different module names
-autodoc_mock_imports += [
+autodoc_mock_imports = list(autodoc_mock_imports) + [
     'adapt',
     'alsaaudio',
     'dateutil',
@@ -73,7 +83,6 @@
 
 todo_include_todos = False
 
-import sphinx_rtd_theme
 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_theme_options = {
diff --git a/mycroft/skills/core.py b/mycroft/skills/core.py
--- a/mycroft/skills/core.py
+++ b/mycroft/skills/core.py
@@ -225,14 +225,18 @@ def __init__(self, name=None, bus=None):
         self._bus = None
         self._enclosure = None
         self.bind(bus)
+        #: Mycroft global configuration. (dict)
         self.config_core = Configuration.get()
         self.config = self.config_core.get(self.name) or {}
         self.dialog_renderer = None
-        self.root_dir = None
+        self.root_dir = None  #: skill root directory
+
+        #: Filesystem access to skill specific folder.
+        #: See mycroft.filesystem for details.
         self.file_system = FileSystemAccess(join('skills', self.name))
         self.registered_intents = []
-        self.log = LOG.create_logger(self.name)
-        self.reload_skill = True  # allow reloading
+        self.log = LOG.create_logger(self.name)  #: Skill logger instance
+        self.reload_skill = True  #: allow reloading (default True)
         self.events = []
         self.scheduled_repeats = []
         self.skill_id = ''  # will be set from the path, so guaranteed unique


Test patch: