diff --git a/jekyllnb/exporter.py b/jekyllnb/exporter.py index eeea9cc..f7f1a82 100644 --- a/jekyllnb/exporter.py +++ b/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 diff --git a/jekyllnb/jekyllnb.py b/jekyllnb/jekyllnb.py index 47c24dc..c2d3063 100644 --- a/jekyllnb/jekyllnb.py +++ b/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 ) diff --git a/jekyllnb/preprocessor.py b/jekyllnb/preprocessor.py index 67ddb88..7b03a7c 100644 --- a/jekyllnb/preprocessor.py +++ b/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", {}))