diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index ec9c53d..83f294f 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,47 +1,80 @@ #=============================================================================== # @file CMakeLists.txt # # @author Guillaume Anciaux # @author Nicolas Richart # # @date Mon Jul 28 12:20:03 2014 # # @brief Principal CMamke for the documentation # # @section LICENSE # # Copyright (©) 2010-2011 EPFL (Ecole Polytechnique Fédérale de Lausanne) # Laboratory (LSMS - Laboratoire de Simulation en Mécanique des Solides) # # LibMultiScale is free software: you can redistribute it and/or modify it under the # terms of the GNU Lesser General Public License as published by the Free # Software Foundation, either version 3 of the License, or (at your option) any # later version. # # LibMultiScale is distributed in the hope that it will be useful, but WITHOUT ANY # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR # A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more # details. # # You should have received a copy of the GNU Lesser General Public License # along with LibMultiScale. If not, see . # #=============================================================================== find_package(Doxygen REQUIRED) SET(LIBMULTISCALE_BUILD_DOXYGEN FALSE CACHE BOOL "Request build of doxygen of LibMultiScale sources" ) if(DOXYGEN_FOUND AND LIBMULTISCALE_BUILD_DOXYGEN) set(DOXYGEN_WARNINGS NO) set(DOXYGEN_QUIET "YES" CACHE STRING "switch to make doxygen quiet or not") mark_as_advanced(DOXYGEN_QUIET) if(CMAKE_VERBOSE_MAKEFILE) set(DOXYGEN_WARNINGS YES) set(DOXYGEN_QUIET "NO" CACHE STRING "switch to make doxygen quiet or not" FORCE) endif(CMAKE_VERBOSE_MAKEFILE) add_subdirectory(doxygen) endif() -# add_subdirectory(manual) +set(file_list_source_files "${CMAKE_CURRENT_BINARY_DIR}/list_source_files") +file(WRITE "${file_list_source_files}" "") + +package_get_all_source_files( + LIBMULTISCALE_SRCS + LIBMULTISCALE_PUBLIC_HDRS + LIBMULTISCALE_PRIVATE_HDRS + ) + +set(LIBMULTISCALE_DEPEND_FILES ${LIBMULTISCALE_SRCS} ${LIBMULTISCALE_PUBLIC_HDRS} ${LIBMULTISCALE_PRIVATE_HDRS}) +foreach(_file ${LIBMULTISCALE_DEPEND_FILES}) + file(APPEND "${file_list_source_files}" + "${_file} +") +endforeach() + +file(COPY source DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) + +add_custom_command( + COMMENT "Parse keyowrds from inline doc" + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/source/keywords.rst + COMMAND python3 ${CMAKE_CURRENT_SOURCE_DIR}/keywords/generate_doc.py ${file_list_source_files} ${CMAKE_CURRENT_BINARY_DIR}/source/keywords.rst + DEPENDS ${LIBMULTISCALE_DEPEND_FILES} + ) + + +add_custom_command( + COMMENT "Launch sphinx" + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/build/html/index.html + COMMAND sphinx-build -M html ${CMAKE_CURRENT_BINARY_DIR}/source ${CMAKE_CURRENT_BINARY_DIR}/build + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/source/keywords.rst + ) + +add_custom_target(libmultiscale-doc DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/build) diff --git a/doc/manual/CMakeLists.txt b/doc/keywords/CMakeLists.txt similarity index 100% rename from doc/manual/CMakeLists.txt rename to doc/keywords/CMakeLists.txt diff --git a/doc/manual/chapters.tex b/doc/keywords/chapters.tex similarity index 100% rename from doc/manual/chapters.tex rename to doc/keywords/chapters.tex diff --git a/doc/manual/main.py b/doc/keywords/generate_doc.py similarity index 90% rename from doc/manual/main.py rename to doc/keywords/generate_doc.py index bdef6fb..cf79fd8 100644 --- a/doc/manual/main.py +++ b/doc/keywords/generate_doc.py @@ -1,200 +1,207 @@ #!/usr/bin/env python3 -import sys +import argparse import os import re import pylibmultiscale as lm import pyparsing as pp from libmultiscale_doc_parser import LibMultiScaleParser -from generate_latex import generateLatex +from generate_rst import generateRST ################################################################ def LMDocData(): return { 'name': None, 'type': None, 'description': None, 'children': [], 'var_name': None, 'c_type': None, 'filename': None, 'heritance': None, 'example': None, 'defaults': None } def LMDataNode(): return { 'name': None, 'children': {}, 'data': [] } ################################################################ def readListOfSourceFiles(fname): _f = open(fname) list_files = [] for line in _f.readlines(): fname = line.strip() if (line == ""): continue _str = open(fname).read() m = re.search(r'.*(declareParams\(\))\s+(\{).*', _str) if not m: continue source_file = fname list_files.append(source_file) return list_files ################################################################ def addDoc(root, doc, _file): dirs = _file.split('/') i = 0 for i in range(0, len(dirs)): if dirs[i] == 'src': break ++i if i == len(dirs): raise RuntimeError("problem in the file structure") dirs = dirs[i+1:] _file = os.path.join(*dirs) print(_file) node = root sublevel = dirs[0] for sublevel in dirs: if sublevel not in node['children']: node['children'][sublevel] = LMDataNode() node = node['children'][sublevel] node['name'] = sublevel node['data'].append(doc) ################################################################ def addDocByName(sorted_by_name, doc, _file): # std: : string short_name = file.stem().native() # // std: : cerr << "record heritance " << short_name << std: : endl # sorted_by_name[protectString(short_name)] = doc pass ################################################################ def generatorInternalKeyWordList(): return [ 'DomainDD', 'DomainAtomic', 'DomainContinuum', 'ActionInterface', 'DomainInterface', 'Dumper', 'ComposedGeom', 'CouplerManager', 'DofAssociation', 'Bridging', 'Geometry', 'ArlequinTemplate', 'PointAssociation', 'LAMMPS_BASE', 'AKANTU_BASE', 'AKANTU_DYNAMIC', 'AKANTU_STATIC', 'FILTER'] ################################################################ def checkKeywordExistance(key, key_list, internal_key_list): if (key not in key_list) and (key not in internal_key_list): print("Warning:Undeclared " + key + ": keywords are " + ', '.join(key_list)) return elif key in key_list: key_list[key].pop() if not key_list[key]: del key_list[key] print("removing key") print('') ################################################################ def main(): - p = sys.argv[1] - files = readListOfSourceFiles(p) + parser = argparse.ArgumentParser( + description='Python embedded in Latex tool') + parser.add_argument('filelist', type=str, + help='The file containing the files to parse') + parser.add_argument('output', type=str, help='The output rst file') + + args = parser.parse_args() + + files = readListOfSourceFiles(args.filelist) key_list = lm.getKeyWordList() internal_key_list = generatorInternalKeyWordList() parser = LibMultiScaleParser() root = LMDataNode() sorted_by_name = {} for fname in files: res_doc = LMDocData() res_doc['filename'] = fname print("parsing " + res_doc['filename']) try: res = parser.parse(fname, internal_key_list) for k, v in res.items(): print(f'{k}:{v}') res_doc['name'] = res['description'][0] res_doc['description'] = res['description'][1] if 'example' in res: res_doc['example'] = res['example'] if 'heritance' in res: res_doc['heritance'] = res['heritance'] if 'keywords' in res: res_doc['children'] = [{'name': k[0], 'value': k} for k in res['keywords']] checkKeywordExistance(res_doc['name'], key_list, internal_key_list) for child in res_doc['children']: child['filename'] = res_doc['filename'] child['description'] = child['value'][1] addDoc(root, res_doc, fname) addDocByName(sorted_by_name, res, fname) except pp.ParseException as e: print(f'{res_doc["filename"]}:{e.lineno}:{e.col}:{e}') except pp.ParseSyntaxException as e: print(f'{res_doc["filename"]}:{e.lineno}:{e.col}:{e}') for k, v in key_list.items(): print("Warning: keyword " + k + " was not documented ") print(root) - fout = open("../source/keywords.rst", 'w') + fout = open(args.output, 'w') fout.write(""" Keywords ======== """) - generateLatex(fout, root, sorted_by_name) + generateRST(fout, root, sorted_by_name) fout.close() ################################################################ if __name__ == "__main__": main() diff --git a/doc/manual/generate_latex.cc b/doc/keywords/generate_latex.cc similarity index 100% rename from doc/manual/generate_latex.cc rename to doc/keywords/generate_latex.cc diff --git a/doc/manual/generate_latex.hh b/doc/keywords/generate_latex.hh similarity index 100% rename from doc/manual/generate_latex.hh rename to doc/keywords/generate_latex.hh diff --git a/doc/manual/generate_latex.py b/doc/keywords/generate_rst.py similarity index 98% rename from doc/manual/generate_latex.py rename to doc/keywords/generate_rst.py index 41841ba..15667cb 100644 --- a/doc/manual/generate_latex.py +++ b/doc/keywords/generate_rst.py @@ -1,251 +1,251 @@ import os def protectString(_str): _str = _str.replace("\n\n", 'qwertzuiop') _str = _str.replace("\n", "") _str = _str.replace('qwertzuiop', "\n\n").strip() return _str def makeTypeString(doc): if 'c_type' not in doc: return "NOT YET ACCESSIBLE" return doc['c_type'] # boost:: smatch what # # const boost:: regex my_filter_quantity_plus_brackets("Quantity<([^,]+),?(.*)>\\[(.*)\\]") # # bool res = boost:: regex_match(doc.c_type, what, my_filter_quantity_plus_brackets) # # if (res){ # std: : cerr << doc.filename.native() << ":0:Error the type " # << doc.c_type << " is invalid" << std: : endl # exit(EXIT_FAILURE) # } # # const boost:: regex my_filter_quantity("Quantity<([^,]+),([^,]+)>") # res = boost:: regex_match(doc.c_type, what, my_filter_quantity) # # if (res) { # // std: : cerr << "AAAAAAA" # const boost: : regex my_filter2("Keyword\\s\\[(.*)\\]") # boost:: smatch what2 # res = boost: : regex_match(doc.type, what2, my_filter2) # if (!res) return doc.c_type # # // std: : cerr << "AAAAAAA " + doc.type << std: : endl # std: : string ret = what2.str(1) # if (what.str(2) != "") ret += " x " # ret += what.str(1) # return ret # } # # const boost:: regex my_filter_single_quantity("Quantity<(.*)>") # res = boost:: regex_match(doc.c_type, what, my_filter_single_quantity) # if (res) { # // std: : cerr << "BBBBBBBBB" # return what.str(1) # } # # const boost:: regex my_filter_brackets("(.*)\\[(.*)\\]") # res = boost: : regex_match(doc.c_type, what, my_filter_brackets) # if (res) { # // std: : cerr << "CCCCCCCC" # const boost: : regex my_filter2("Keyword\\s\\[(.*)\\]") # boost:: smatch what2 # res = boost: : regex_match(doc.type, what2, my_filter2) # if (!res) return doc.c_type # # std: : string ret = what2.str(1) # if (what.str(2) != "") ret += " x " # ret += what.str(1) # return ret # } # # return doc.c_type # } raise def getSubPath(_file): dirs = _file.split('/') i = 0 for i in range(0, len(dirs)): if dirs[i] == 'src': break ++i if i == len(dirs): raise RuntimeError("problem in the file structure") return os.path.join(*dirs[i:]) def getMainSection(_file): dirs = _file.split('/') i = 0 for i in range(0, len(dirs)): if dirs[i] == 'src': break ++i if i == len(dirs): raise RuntimeError("problem in the file structure") return dirs[i+1] def generateSyntax(fout, doc, level): func_name = "syntax " + getMainSection(doc['filename']) params = [doc['name']] # fout.write(f"{func_name} {params}\n\n") generateLatexSection(fout, "**Syntax**", level+1) fout.write(f"TODO\n\n") def generateLatexSection(fout, title, level): # params = [label, level, title, label] if level == 0: sep = '=' elif level == 1: sep = '-' elif level == 2: sep = '`' elif level == 3: sep = '~' elif level == 4: sep = '~' else: raise RuntimeError("what the fuck ", level) fout.write(f''' {title} {sep*len(title)} ''') def generateKeywordsLatexBloc(fout, keywords, level): if not keywords: return key_list = ", ".join([k['name'] for k in keywords]) generateLatexSection(fout, "**Keywords** " + f"({key_list})", level+1) fout.write("\n\n\n") for i, keyword in enumerate(keywords): name = keyword['name'] description = protectString(keyword['description']) default = "*MANDATORY*" # params = [keyword['name'], makeTypeString(keyword), # # keyword['var_name'], # ] if 'defaults' not in keyword: default = "(**MANDATORY**)" else: default = f"Default: {keyword['defaults']}" fout.write(f""" - **{name}** : {description}. {default} """) def generateHeritanceList(doc, hlist, sorted_by_name): heritance = doc['heritance'] for i, class_name in enumerate(heritance): if class_name not in sorted_by_name: print(doc['filename'] + ":0:" + "Error: Unknown heritance " + class_name) continue if class_name not in hlist: hlist[class_name] = 0 hlist[class_name] += 1 print(f"hlist[{class_name}] = {hlist[class_name]}") herit = sorted_by_name[class_name] generateHeritanceList(herit, hlist) def generateHeritance(fout, doc, hlist, sorted_by_name): heritance = doc['heritance'] for i, class_name in enumerate(heritance): if class_name not in sorted_by_name: print(doc['filename'] + ":0:" + "Error: Unknown heritance " + class_name) continue if class_name not in hlist: print("internal error") continue if hlist[class_name] > 1: hlist[class_name] -= 1 print("not outputing " + class_name, "since hlist[" + class_name + "] = " + hlist[class_name]) herit = sorted_by_name[class_name] sstr = class_name + "[\\ref{" + class_name + "}]" fout.write("heritance" + sstr) fout.write(herit.children) fout.write(herit, hlist) def generateClassInfo(fout, doc, sorted_by_name, level): # get heritance info hlist = {} generateHeritanceList(doc, hlist, sorted_by_name) print("4 " + doc['name'] + " heritance is") for k, v in hlist.items(): print(k + ":", v) description = protectString(doc['description'].strip()) generateLatexSection(fout, "**Description**", level+1) if description != "": fout.write(f"{description}\n\n") generateSyntax(fout, doc, level) if doc['example']: generateLatexSection(fout, "**Examples**", level+1) print('AAAA', doc['example']) examples = doc['example'][0].strip().replace( '\n', '').split(r"COMPUTE") print('AAAA', examples) for ex in examples[1:]: print(ex) fout.write('- COMPUTE ' + ex + "\n") generateLatexSection( fout, "**File** " + f"{getSubPath(doc['filename'])}", level+1) generateKeywordsLatexBloc(fout, doc['children'], level) generateHeritance(fout, doc, hlist, sorted_by_name) -def generateLatex(fout, sorted_by_section, sorted_by_name, level=0): +def generateRST(fout, sorted_by_section, sorted_by_name, level=0): if sorted_by_section['children']: if level != 0: generateLatexSection( fout, sorted_by_section['name'], level) fout.write("\n------------\n") for name, child in sorted_by_section['children'].items(): - generateLatex(fout, child, sorted_by_name, level+1) + generateRST(fout, child, sorted_by_name, level+1) else: for data in sorted_by_section['data']: generateLatexSection(fout, data['name'], level) generateClassInfo(fout, data, sorted_by_name, level) fout.write("\n------------\n") diff --git a/doc/manual/images/bridging-zone-BM.svg b/doc/keywords/images/bridging-zone-BM.svg similarity index 100% rename from doc/manual/images/bridging-zone-BM.svg rename to doc/keywords/images/bridging-zone-BM.svg diff --git a/doc/manual/images/geom-circle-hole1d.svg b/doc/keywords/images/geom-circle-hole1d.svg similarity index 100% rename from doc/manual/images/geom-circle-hole1d.svg rename to doc/keywords/images/geom-circle-hole1d.svg diff --git a/doc/manual/images/geom-circle-hole2d.svg b/doc/keywords/images/geom-circle-hole2d.svg similarity index 100% rename from doc/manual/images/geom-circle-hole2d.svg rename to doc/keywords/images/geom-circle-hole2d.svg diff --git a/doc/manual/images/geom-circle.svg b/doc/keywords/images/geom-circle.svg similarity index 100% rename from doc/manual/images/geom-circle.svg rename to doc/keywords/images/geom-circle.svg diff --git a/doc/manual/images/geom-cube-hole1d.svg b/doc/keywords/images/geom-cube-hole1d.svg similarity index 100% rename from doc/manual/images/geom-cube-hole1d.svg rename to doc/keywords/images/geom-cube-hole1d.svg diff --git a/doc/manual/images/geom-cube-hole2d.svg b/doc/keywords/images/geom-cube-hole2d.svg similarity index 100% rename from doc/manual/images/geom-cube-hole2d.svg rename to doc/keywords/images/geom-cube-hole2d.svg diff --git a/doc/manual/images/geom-cube.svg b/doc/keywords/images/geom-cube.svg similarity index 100% rename from doc/manual/images/geom-cube.svg rename to doc/keywords/images/geom-cube.svg diff --git a/doc/manual/images/planar-impulse.png b/doc/keywords/images/planar-impulse.png similarity index 100% rename from doc/manual/images/planar-impulse.png rename to doc/keywords/images/planar-impulse.png diff --git a/doc/manual/images/radial-impulse.png b/doc/keywords/images/radial-impulse.png similarity index 100% rename from doc/manual/images/radial-impulse.png rename to doc/keywords/images/radial-impulse.png diff --git a/doc/manual/introduction.tex b/doc/keywords/introduction.tex similarity index 100% rename from doc/manual/introduction.tex rename to doc/keywords/introduction.tex diff --git a/doc/manual/libmultiscale_doc_parser.cc b/doc/keywords/libmultiscale_doc_parser.cc similarity index 100% rename from doc/manual/libmultiscale_doc_parser.cc rename to doc/keywords/libmultiscale_doc_parser.cc diff --git a/doc/manual/libmultiscale_doc_parser.hh b/doc/keywords/libmultiscale_doc_parser.hh similarity index 100% rename from doc/manual/libmultiscale_doc_parser.hh rename to doc/keywords/libmultiscale_doc_parser.hh diff --git a/doc/manual/libmultiscale_doc_parser.py b/doc/keywords/libmultiscale_doc_parser.py similarity index 100% rename from doc/manual/libmultiscale_doc_parser.py rename to doc/keywords/libmultiscale_doc_parser.py diff --git a/doc/manual/list_files.txt b/doc/keywords/list_files.txt similarity index 100% rename from doc/manual/list_files.txt rename to doc/keywords/list_files.txt diff --git a/doc/manual/lm_doc_data.hh b/doc/keywords/lm_doc_data.hh similarity index 100% rename from doc/manual/lm_doc_data.hh rename to doc/keywords/lm_doc_data.hh diff --git a/doc/manual/main.cc b/doc/keywords/main.cc similarity index 100% rename from doc/manual/main.cc rename to doc/keywords/main.cc diff --git a/doc/manual/manual-macros.sty b/doc/keywords/manual-macros.sty similarity index 100% rename from doc/manual/manual-macros.sty rename to doc/keywords/manual-macros.sty diff --git a/doc/manual/manual.cls b/doc/keywords/manual.cls similarity index 100% rename from doc/manual/manual.cls rename to doc/keywords/manual.cls diff --git a/doc/manual/manual.sty b/doc/keywords/manual.sty similarity index 100% rename from doc/manual/manual.sty rename to doc/keywords/manual.sty diff --git a/doc/manual/manual.tex b/doc/keywords/manual.tex similarity index 100% rename from doc/manual/manual.tex rename to doc/keywords/manual.tex diff --git a/doc/manual/manual_html.tex b/doc/keywords/manual_html.tex similarity index 100% rename from doc/manual/manual_html.tex rename to doc/keywords/manual_html.tex diff --git a/doc/manual/syntax.tex b/doc/keywords/syntax.tex similarity index 100% rename from doc/manual/syntax.tex rename to doc/keywords/syntax.tex