Docs

This module is used to automatically generate HTML-based documentation for Python scripts with NumPy/SciPy format docstrings and correct code and syntax conventions followed throughout. Please see NumPy/SciPy docstrings formatting guidance here: https://numpydoc.readthedocs.io/en/latest/format.html

Classes

Functions

• extract_params

  extract_params(text)
  
  

  Function used to extract parameters from a function docstring.

  text	Parameters section of a function docstring. For example what you are reading right now is within the parameters section of the extract_params docstring.




• extract_functions

  extract_functions(code)
  
  

  Function used to extract functions from Python code.

  code	Python code containing functions to be extracted.




• extract_module

  extract_module(code)
  
  

  Function used to extract the top block quote containing key information on the Python script. Including module name, developers, and description.

  code	Python code containing the module description in the first block quote. Should containing module name first, developers on a line following 'Developers:', and description last, beginning on a line following 'Description:'.




• functions_html

  functions_html(funcs)
  
  

  Function used to build HTML code from a dictionary of functions.

  funcs	Dictionary containing functions. Must be function name as dictionary key, function parameters within 'parameters', and function description within 'description'. Another dictionary for each function parameter should be included for each paramter within 'parameters', this will contain parameter description, datatype, and whether it is an optional parameter or not.




• build_navbar

  build_navbar(to_include, docs_dir)
  
  

  Function for building a navigation bar 'navbar.js'. This will be saved to the templates folder within the docs directory.

  to_include	List of scripts or classes to add to the navbar. These should be given in the 'module' name format given to the DocsBuilder class so that the links are built correctly.
  docs_dir*	The local/global path to the documentation directory. This should contain a 'templates' folder which would contain Bootstrap codes and this navbar. If it does not exist this function will add the folder.




• build_readme

  build_readme(pages, markdown)
  
  

  Function to build a top level readme.html file. This will link to other pages. A user should use this to document their project as a whole.

  pages	A list of Python scripts turned pages. Top-level pages will be linked to along with their descriptions.
  markdown*	The local/global path to the project readme written in markdown. This will be converted into HTML and merged with the pages html section if given. The default is None """




• build_page

  build_page(module, devs, desc, classes, funcs, submodule)
  
  

  Function for building HTML docs using extracted data.

  module	String containing the module name.
  devs	String containing the names of script developers.
  desc	String describing the module.
  classes*	Dictionary containing classes and their description, code, functions, and variables. The default is "".
  funcs*	Dictionary containing functions and their descriptions and parameters. The default is "".
  submodule*	String containing the submodule name, if within a submodule, eg class. The default is "".




• output

  output(path, overwrite)
  
  

  Function to control saving of HTML files.

  path*	String containing the local/global filepath to the Documentation directory. The HTML files will be saved here. The default is 'docs'.
  overwrite*	True/False determining whether pre-existing files will be overwritten without warning. If False then overwrite will still be possible but a warning will appear if there are any pre-existing files, which will confirm the user's intention in overwritting or otherwise.




• bootstrap_download

  bootstrap_download(docs_dir)
  
  

  Function used for downloading Bootstrap files. These are downloaded from this projects GitHub repo.

  docs_dir	The local/global path to the documentation directory.