Source code for ccpn.core.lib.Documentation

"""Generation of Sphinx automatic documentation

"""
#=========================================================================================
# Licence, Reference and Credits
#=========================================================================================
__copyright__ = "Copyright (C) CCPN project (http://www.ccpn.ac.uk) 2014 - 2020"
__credits__ = ("Ed Brooksbank, Luca Mureddu, Timothy J Ragan & Geerten W Vuister")
__licence__ = ("CCPN licence. See http://www.ccpn.ac.uk/v3-software/downloads/license")
__reference__ = ("Skinner, S.P., Fogh, R.H., Boucher, W., Ragan, T.J., Mureddu, L.G., & Vuister, G.W.",
                 "CcpNmr AnalysisAssign: a flexible platform for integrated NMR analysis",
                 "J.Biomol.Nmr (2016), 66, 111-124, http://doi.org/10.1007/s10858-016-0060-y")
#=========================================================================================
# Last code modification
#=========================================================================================
__modifiedBy__ = "$modifiedBy: Ed Brooksbank $"
__dateModified__ = "$dateModified: 2020-02-11 17:32:53 +0000 (Tue, February 11, 2020) $"
__version__ = "$Revision: 3.0.1 $"
#=========================================================================================
# Created
#=========================================================================================
__author__ = "$Author: rhf22 $"
__date__ = "$Date: 2017-04-07 10:28:41 +0000 (Fri, April 07, 2017) $"
#=========================================================================================
# Start of code
#=========================================================================================
"""Scrips to (re)create project sphinx documentation"""

import typing

import subprocess
import os
import re
import shutil
from sphinx.ext import apidoc
from ccpn.framework import Version
from ccpn.util import Path as corePath


joinPath = corePath.joinPath

# Relative path to documentation directory
documentationPath = 'doc'

ll = ('__pycache__', 'testing', 'api', 'xml', 'data', 'macros', 'chemBuild', 'Bmrb',
      'v_\d+_\d+_.*')
skipSubDirectories = re.compile('|'.join(ll))


[docs]def refreshSphinxDocumentation(): """(Re)create sphinx documentation. Locations are hardwired""" pythonDirectory = corePath.getPythonDirectory() topDirectory = corePath.getTopDirectory() docDirectory = joinPath(topDirectory, documentationPath) # Direwcteories that should not be documented excludeTopDirs = ('chemBuild', '__pycache__') inputDirectories = list(x for x in os.scandir(pythonDirectory) if x.is_dir() and x.name not in excludeTopDirs) # Remove sphinx-apidoc files outputDirs = {} for dirEntry in inputDirectories: inDirectory = joinPath(docDirectory, 'source', dirEntry.name) outputDirs[dirEntry.name] = inDirectory if os.path.exists(inDirectory): print("Removing %s" % inDirectory) shutil.rmtree(inDirectory) os.mkdir(inDirectory) # clean builds subprocess.call(['make', '-C', docDirectory, 'clean']) # # Recreate apidoc # precommand = ['sphinx-apidoc'] # # documentation target - filled in below # precommand.extend(('-o', 'output TBD')) # # Put module documentation before submodule documentation: # precommand.append('--module-first') # # Project name header: # precommand.extend(('-A', Version.authors)) # # Project name header: # precommand.extend(('-V', Version.applicationVersion)) # # Project name header: # precommand.extend(('-R', Version.revision)) # # # Generate documentation - ccpn: # for dirEntry in inputDirectories: # module = dirEntry.name # target = dirEntry.path # skipDirs = getNamedSubdirectories(target, skipSubDirectories) # command = precommand + ['-H', 'CCPN', target] + skipDirs # if module == 'ccpnmodel': # # Skip an additional directory # command.append(os.path.join(target, 'ccpncore', 'memops', 'scripts', 'model')) # command[2] = outputDirs[module] # apidoc.main(command) # NOTE:ED - ordering is incorrect # Recreate apidoc # precommand = ['sphinx-apidoc'] precommand = [] # Put module documentation before submodule documentation: precommand.append('--module-first') # Project name header: precommand.extend(('-A', Version.__credits__)) # Project name header: precommand.extend(('-V', Version.applicationVersion)) # Project name header: precommand.extend(('-R', Version.revision)) # # documentation target - filled in below # precommand.extend(('-o', 'output TBD')) # Generate documentation - ccpn: for dirEntry in inputDirectories: module = dirEntry.name target = dirEntry.path skipDirs = getNamedSubdirectories(target, skipSubDirectories) # command = precommand + ['-H', 'CCPN', target] + skipDirs command = precommand + ['-H', 'CCPN'] + ['-o', outputDirs[module], target] + skipDirs if module == 'ccpnmodel': # Skip an additional directory command.append(os.path.join(target, 'ccpncore', 'memops', 'scripts', 'model')) # command[2] = outputDirs[module] apidoc.main(command) # rebuild docs subprocess.call(['make', '-C', docDirectory, 'html'])
[docs]def getNamedSubdirectories(path, matchExpression=None) -> typing.List[str]: """Get a list of all subdirectories of path whose basename starts with one of the prefixes Does not look inside the selected subdirectories""" result = [] if matchExpression is not None: for root, dirs, files in os.walk(path): if matchExpression.fullmatch(os.path.basename(root)) is not None: result.append(root) del dirs[:] # return result
if __name__ == '__main__': refreshSphinxDocumentation()