Add tools for creating rst pages for functions, classes and tutorials

tools/documentation/_rst_templates/class.rst.template

@@ -0,0 +1,7 @@
+{{ function_name }}
+{{ function_header_underline }}
+
+.. mat:module:: {{ module_name }}
+.. autoclass:: {{ full_function_name }}
+    :members:
+    :show-inheritance:

tools/documentation/_rst_templates/function.rst.template

@@ -0,0 +1,5 @@
+{{ function_name }}
+{{ function_header_underline }}
+
+.. mat:module:: .
+.. autofunction:: {{ full_function_name }}

tools/documentation/_rst_templates/index_core_types.rst.template

@@ -0,0 +1,10 @@
+Neurodata Types
+===============
+
+These are the MatNWB neurodata types from the core schema specification.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Functions
+
+{{ function_list }}

tools/documentation/_rst_templates/index_functions.rst.template

@@ -0,0 +1,10 @@
+MatNWB Functions
+================
+
+These are the main functions of the MatNWB API
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Functions
+
+{{ function_list }}

tools/documentation/_rst_templates/index_tutorials.rst.template

@@ -0,0 +1,8 @@
+Tutorials
+=========
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials
+
+{{ file_list }}

tools/documentation/_rst_templates/tutorial.rst.template

@@ -0,0 +1,6 @@
+{{tutorial_name}}
+===============================
+
+.. raw:: html
+
+   <iframe src="{{static_html_path}}" style="width: 900px; height: 100vh; overflow: hidden; border: none;"></iframe>

tools/documentation/matnwb_generateRstFilesFromCode.m

@@ -0,0 +1,5 @@
+function matnwb_generateRstFilesFromCode()
+    generateRstForTutorials()
+    generateRstForNwbFunctions()
+    generateRstForNwbTypeClasses()
+end

tools/documentation/private/filewrite.m

@@ -0,0 +1,5 @@
+function filewrite(filePath, text)
+    fid = fopen(filePath, 'wt');
+    fwrite(fid, text);
+    fclose(fid);
+end

tools/documentation/private/fillTemplate.m

@@ -0,0 +1,9 @@
+function template = fillTemplate(template, data)
+    fields = fieldnames(data);
+    for i = 1:numel(fields)
+        if ~isstruct(data.(fields{i})) && ~iscell(data.(fields{i}))
+            placeholder = sprintf('{{ %s }}', fields{i});
+            template = strrep(template, placeholder, string(data.(fields{i})));
+        end
+    end
+end

tools/documentation/private/generateRstForNwbFunctions.m

@@ -0,0 +1,52 @@
+function generateRstForNwbFunctions()
+% generateRstForNwbFunctions 
+
+    % List, filter and sort files to generate. Todo: simplify
+    rootDir = misc.getMatnwbDir();
+    rootFiles = dir(rootDir);
+    rootFileNames = {rootFiles.name};
+    rootWhitelist = {'nwbRead.m', 'NwbFile.m', 'nwbExport.m', 'generateCore.m', 'generateExtension.m', 'nwbClearGenerated.m'};%, 'nwbInstallExtension.m'};
+    isWhitelisted = ismember(rootFileNames, rootWhitelist);
+
+    rootFiles(~isWhitelisted) = [];
+
+    [~, ~, iC] = intersect(rootWhitelist, {rootFiles.name}, 'stable');
+    rootFiles = rootFiles(iC);
+
+    docsSourceRootDir = fullfile(misc.getMatnwbDir, 'docs', 'source');
+    exportDir = fullfile(docsSourceRootDir, 'pages', 'functions');
+    if ~isfolder(exportDir); mkdir(exportDir); end
+
+    functionTemplate = fileread( getRstTemplateFile('function') );
+    classTemplate = fileread( getRstTemplateFile('class') );
+
+    for i = 1:numel(rootFiles)
+        iFile = fullfile(rootFiles(i).folder, rootFiles(i).name);
+        [~, functionName] = fileparts(iFile);
+
+        mc = meta.class.fromName(functionName);
+        if isempty(mc)
+            currentTemplate = functionTemplate;
+        else
+            currentTemplate = classTemplate;
+        end
+
+        data.function_name = functionName;
+        data.module_name = '.';
+        data.function_header_underline = repmat('=', 1, numel(functionName));
+        data.full_function_name = functionName;
+
+        thisRst = fillTemplate(currentTemplate, data);
+        rstFilePath = fullfile(exportDir, [functionName, '.rst']);
+        filewrite(rstFilePath, thisRst);
+    end
+
+    % Create index
+    indexTemplate = fileread( getRstTemplateFile('index_functions') );
+    [~, functionNames] = fileparts(string({rootFiles.name}));
+    data.function_list = strjoin("   "+functionNames, newline);
+
+    thisRst = fillTemplate(indexTemplate, data);
+    rstFilePath = fullfile(exportDir, ['index', '.rst']);
+    filewrite(rstFilePath, thisRst);
+end

tools/documentation/private/generateRstForNwbTypeClasses.m

@@ -0,0 +1,43 @@
+function generateRstForNwbTypeClasses()
+% generateRstForNwbTypeClasses Generate rst files for each Neurodata matnwb class
+
+    rootDir = misc.getMatnwbDir();
+    coreTypeFiles = dir(fullfile(rootDir, '+types', '+core', '*.m'));
+
+    docsSourceRootDir = fullfile(misc.getMatnwbDir, 'docs', 'source');
+    exportDir = fullfile(docsSourceRootDir, 'pages', 'neurodata_types', 'core');
+    if ~isfolder(exportDir); mkdir(exportDir); end
+
+    functionTemplate = fileread( getRstTemplateFile('function') );
+    classTemplate = fileread( getRstTemplateFile('class') );
+
+    for i = 1:numel(coreTypeFiles)
+        iFile = fullfile(coreTypeFiles(i).folder, coreTypeFiles(i).name);
+        [~, functionName] = fileparts(iFile);
+
+        data.function_name = functionName;
+        data.module_name = 'types.core';
+        data.function_header_underline = repmat('=', 1, numel(functionName));
+        data.full_function_name = sprintf('types.core.%s', functionName);
+
+        mc = meta.class.fromName(data.full_function_name);
+        if isempty(mc)
+            currentTemplate = functionTemplate;
+        else
+            currentTemplate = classTemplate;
+        end
+
+        thisRst = fillTemplate(currentTemplate, data);
+        rstFilePath = fullfile(exportDir, [functionName, '.rst']);
+        filewrite(rstFilePath, thisRst);
+    end
+
+    % Create index
+    indexTemplate = fileread( getRstTemplateFile('index_core_types') );
+    [~, functionNames] = fileparts(string({coreTypeFiles.name}));
+    data.function_list = strjoin("   "+functionNames, newline);
+
+    thisRst = fillTemplate(indexTemplate, data);
+    rstFilePath = fullfile(exportDir, ['index', '.rst']);
+    filewrite(rstFilePath, thisRst);
+end

tools/documentation/private/generateRstForTutorials.m

@@ -0,0 +1,38 @@
+function generateRstForTutorials()
+% generateRstForTutorials - Generate rst files for all the tutorial HTML files
+
+    docsSourceRootDir = fullfile(misc.getMatnwbDir, 'docs', 'source');
+
+    tutorialHtmlSourceDir = fullfile(docsSourceRootDir, '_static', 'html', 'tutorials');
+    tutorialRstTargetDir = fullfile(docsSourceRootDir, 'pages', 'tutorials');
+    if ~isfolder(tutorialRstTargetDir); mkdir(tutorialRstTargetDir); end
+
+    rstTemplate = fileread( getRstTemplateFile('tutorial') );
+
+    % List all html files in source dir
+    L = dir(fullfile(tutorialHtmlSourceDir, '*.html'));
+
+    for i = 1:numel(L)
+        thisFilePath = fullfile(L(i).folder, L(i).name);
+        relPath = strrep(thisFilePath, docsSourceRootDir, '../..');
+
+        [~, name] = fileparts(relPath);
+
+        rstOutput = replace(rstTemplate, '{{static_html_path}}', relPath);
+        rstOutput = replace(rstOutput, '{{tutorial_name}}', name);
+
+        rstOutputFile = fullfile(tutorialRstTargetDir, [name, '.rst']);
+        fid = fopen(rstOutputFile, 'wt');
+        fwrite(fid, rstOutput);
+        fclose(fid);
+    end
+
+    % Create index
+    indexTemplate = fileread( getRstTemplateFile('index_tutorials') );
+    [~, fileNames] = fileparts(string({L.name}));
+    data.file_list = strjoin("   "+fileNames, newline);
+
+    thisRst = fillTemplate(indexTemplate, data);
+    rstFilePath = fullfile(tutorialRstTargetDir, ['index', '.rst']);
+    filewrite(rstFilePath, thisRst);
+end

tools/documentation/private/getRstTemplateFile.m

@@ -0,0 +1,16 @@
+function templateFilePath = getRstTemplateFile(templateName)
+    arguments
+        templateName (1,1) string
+    end
+    fileName = templateName + ".rst.template";
+
+    templateFilePath = fullfile(...
+        misc.getMatnwbDir, ...
+        "tools", ...
+        "documentation", ...
+        "_rst_templates", ...
+        fileName );
+
+    assert(isfile(templateFilePath), ...
+        'Template filepath not found for template with name "%s"', templateName)
+end