Add comments to source files

Closes #119

jekyllnb/exporter.py

@@ -7,37 +7,55 @@
 
 
 class JekyllExporter(MarkdownExporter):
+    """Exporter to write Markdown with Jekyll metadata"""
+
     resources = {}
 
-    def from_filename(self, filename, resources=None, **kw):
+    def from_filename(self, filename, resources=None, **kwargs):
+        """Convert notebook from a file
+
+        Args:
+            filename (str): Full filename of the notebook to convert.
+            resources (dict): Additional resources used by preprocessors and filters.
+            `**kwargs`: Ignored
+
+        Returns:
+            NotebookNode: Converted notebook.
+            dict: Resources dictionary.
+        """
         self.resources = resources
         return super(JekyllExporter, self).from_filename(
-            filename, resources=resources, **kw
+            filename, resources=resources, **kwargs
         )
 
     @default("template_file")
     def _template_file_default(self):  # skipcq: PYL-R0201
+        """Default template file"""
         return "jekyll"
 
     @property
     def template_path(self):
+        """Path to available template files"""
         return super(JekyllExporter, self).template_path + [
             os.path.join(os.path.dirname(__file__), "templates")
         ]
 
     @property
     def preprocessors(self):
+        """Add JekyllPreprocessor to list of enabled preprocessors"""
         return super(JekyllExporter, self).preprocessors + [
             "jekyllnb.JekyllPreprocessor"
         ]
 
     @property
     def default_config(self):
+        """Default configuration"""
         config = Config({"JekyllPreprocessor": {"enabled": True}})
         config.merge(super(JekyllExporter, self).default_config)
         return config
 
     def default_filters(self):
+        """Default filters"""
         for pair in super(JekyllExporter, self).default_filters():
             yield pair
 

jekyllnb/jekyllnb.py

@@ -29,6 +29,8 @@
 
 
 class JekyllNB(NbConvertApp):
+    """Application to convert notebooks (``*.ipynb``) to Jekyll Markdown (``.md``)"""
+
     name = "jupyter-jekyllnb"
     description = "Convert Jupyter notebooks to Jekyll-ready Markdown"
     version = __version__
@@ -42,10 +44,12 @@ class JekyllNB(NbConvertApp):
 
     @default("export_format")
     def _export_format_default(self):  # skipcq: PYL-R0201
+        """Default export format"""
         return "jekyll"
 
     @observe("export_format")
     def _export_format_changed(self, change):
+        """Ensure export format is jekyll"""
         default_format = self._export_format_default()
 
         if change["new"].lower() != default_format:
@@ -57,6 +61,7 @@ def _export_format_changed(self, change):
 
     @catch_config_error
     def initialize(self, argv=None):
+        """Initialize application, notebooks, writer, and postprocessor"""
         super(JekyllNB, self).initialize(argv)
         self.writer.build_directory = os.path.join(self.site_dir, self.page_dir)
 
@@ -66,6 +71,21 @@ def initialize(self, argv=None):
             )
 
     def init_single_notebook_resources(self, notebook_filename):
+        """Initialize resources
+
+        Initializes the resources dictionary for a single notebook.
+
+        Args:
+            notebook_filename (str): Full filename of the notebook to convert.
+
+        Returns:
+            dict: Resources dictionary for a single notebook.
+
+            Dictionary must include the following keys:
+                - config_dir: location of the Jupyter config directory
+                - unique_key: notebook name
+                - output_files_dir: directory where output files should be saved
+        """
         resources = super(JekyllNB, self).init_single_notebook_resources(
             notebook_filename
         )

jekyllnb/preprocessor.py

@@ -2,7 +2,21 @@
 
 
 class JekyllPreprocessor(Preprocessor):
+    """Preprocessor to add Jekyll metadata"""
+
     def preprocess(self, nb, resources):  # skipcq: PYL-R0201
+        """Preprocess notebook
+
+        Add Jekyll metadata to notebook resources.
+
+        Args:
+            nb (NotebookNode): Notebook being converted.
+            resources (dict): Additional resources used by preprocessors and filters.
+
+        Returns:
+            NotebookNode: Modified notebook.
+            dict: Modified resources dictionary.
+        """
         name = resources["metadata"]["name"]
         metadata = {"layout": "page", "title": name, "permalink": "/" + name}
         metadata.update(nb.metadata.get("jekyll", {}))