\n"
"
\n\n")
a_file.write(top)
#Menu - user specified links.
navigation = ("\n\n"
a_file.write(navigation)
#Main content.
content = "\n")
if project.logo_file is not None and project.logo_file != "":
top += ("![\""](\"images/logo.png\")
")
top += (""
"$(PROJECT_NAME) $(PROJECT_VERSION) API documentation\n"
"
\n")
top += (""
"$(PROJECT_NAME) $(PROJECT_VERSION) API documentation\n"
"\n
\n"
a_file.write(content)
a_file.write(template_footer)
a_file.write("\n\n")
def add_logo(project, output_dir):
"""Copy the logo, if any, to images/logo.png ."""
if(project.logo_file is None or project.logo_file == ""):
return
images_path = os.path.join(output_dir, "images")
os.makedirs(images_path, exist_ok=True)
shutil.copy(project.logo_file, os.path.join(images_path, "logo.png"))
def generate_style(filename):
"""Write default css to a file"""
with open(filename, mode="w", encoding="utf-8") as a_file:
a_file.write(default_css)
def add_css(css, output_dir):
"""Copy the CSS if specified, write default CSS otherwise."""
css_path = os.path.join(output_dir, "css")
os.makedirs(css_path, exist_ok=True)
css_path = os.path.join(css_path, "style.css")
if css is None or css == "":
generate_style(css_path)
return
shutil.copy(css, css_path)
def generate_index(filename):
"""Write default index to a file"""
with open(filename, mode="w", encoding="utf-8") as a_file:
a_file.write("Ddoc\n\n")
a_file.write("Macros:\n")
a_file.write(" TITLE=$(PROJECT_NAME) $(PROJECT_VERSION) API documentation\n\n")
def add_index(index, output_dir):
"""Copy the index if specified, write default index otherwise."""
index_path = os.path.join(output_dir, "index.dd")
if index is None or index == "":
generate_index(index_path)
return
shutil.copy(index, index_path)
def generate_ddoc(sources, output_dir, ddoc_template, ddoc_command):
"""Generate documentation from sources, writing it to output_dir."""
#Generate index html with ddoc.
index_ddoc = os.path.join(output_dir, "index.dd")
index_html = os.path.join(output_dir, "index.html")
run_cmd(ddoc_command + " -Df" + index_html + " " + index_ddoc)
os.remove(index_ddoc)
#Now generate html for the sources.
for source in sources:
out_path = os.path.join(output_dir, module_name(source)) + ".html"
run_cmd(ddoc_command + " -Df" + out_path + " " + source)
def generate_config(filename):
"""Generate default AutoDDoc config file."""
with open(filename, mode="w", encoding="utf-8") as a_file:
a_file.write(default_cfg)
def init_parser():
"""Initialize and return the command line parser."""
autoddoc_description =\
("AutoDDoc 0.1\n"
"Documentation generator script for D using DDoc.\n"
"Copyright Ferdinand Majerech 2011.\n\n"
"AutoDDoc scans subdirectories of the current directory for D or DDoc\n"
"sources (.d, .dd or .ddoc) and generates documentation using settings\n"
"from a configuration file.\n"
"NOTE: AutoDDoc will only work if package/module hierarchy matches the\n"
"directory hierarchy, so e.g. module 'pkg.util' would be in file './pkg/util.d' .")
autoddoc_epilog =\
("\nTutorial:\n"
"1. Copy the script to your project directory and move into that directory.\n"
" Relative to this directory, module names must match their filenames,\n"
" so e.g. module 'pkg.util' would be in file './pkg/util.d' .\n"
"2. Generate AutoDDoc configuation file. To do this, type\n"
" './autoddoc.py -g'. This will generate file 'autoddoc.cfg' .\n"
"3. Edit the configuation file. Set project name, version, output\n"
" directory and other parameters.\n"
"4. Generate the documentation by typing './autoddoc.py' .\n")
parser = argparse.ArgumentParser(description= autoddoc_description,
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog = autoddoc_epilog, add_help=True)
parser.add_argument("config_file", nargs="?", default="autoddoc.cfg",
help="Configuration file to use to generate documentation. "
"Can not be used with any optional arguments. "
"If not specified, 'autoddoc.cfg' is assumed. "
"Examples: 'autoddoc.py config.cfg' "
"will generate documentation using file 'config.cfg' . "
"'autoddoc.py' will generate documentation "
"using file 'autoddoc.cfg' if it exists.",
metavar="config_file")
parser.add_argument("-g", "--gen-config", nargs="?", const="autoddoc.cfg",
help="Generate default AutoDDoc configuation file. "
"config_file is the filename to use. If not specified, "
"autoddoc.cfg is used.",
metavar="config_file")
parser.add_argument("-s", "--gen-style", nargs="?", const="autoddoc_style.css",
help="Generate default AutoDDoc style sheet. "
"css_file is the filename to use. If not specified, "
"autoddoc_style.css is used.",
metavar="css_file")
parser.add_argument("-i", "--gen-index", nargs="?", const="autoddoc_index.dd",
help="Generate default AutoDDoc documentation index. "
"index_file is the filename to use. If not specified, "
"autoddoc_index.dd is used.",
metavar="index_file")
return parser
def main():
parser = init_parser()
args = parser.parse_args()
#Generate config/style/index if requested.
done = False;
try:
if args.gen_config is not None:
generate_config(args.gen_config)
done = True
if args.gen_style is not None:
generate_style(args.gen_style)
done = True
if args.gen_index is not None:
generate_index(args.gen_index)
done = True
except IOError as error:
print("\nERROR: Unable to generate:", error)
return
if done or args.config_file is None:
return
if not os.path.isfile(args.config_file):
print("\nERROR: Can't find configuration file", args.config_file, "\n")
parser.print_help()
return
#Load documentation config.
config = configparser.ConfigParser()
try:
config.read(args.config_file)
project = config["PROJECT"]
project = ProjectInfo(project["name"],
project["version"],
project["copyright"],
project["logo"])
output = config["OUTPUT"]
output_dir = output["directory"]
if output_dir == "":
output_dir = "autoddoc"
css = output["style"]
index = output["index"]
links = []
if output["links"] != "":
for link in output["links"].split(","):
parts = link.split(" ", 1)
links.append((parts[0].strip(), parts[1].strip()))
ignore = output["ignore"].split(",")
if ignore == [""]:
ignore = []
ddoc_line = config["DDOC"]["ddoc_command"]
except configparser.Error as error:
print("Unable to parse configuration file", args.config_file, ":", error)
return
except IOError as error:
print("Unable to read configuration file", args.config_file, ":", error)
return
#Do the actual generation work.
try:
#Find all .d, .dd, .ddoc files.
sources = scan_sources(".", ignore)
ddoc_template = os.path.join(output_dir, "AUTODDOC_TEMPLATE.ddoc")
os.makedirs(output_dir, exist_ok=True)
add_template(ddoc_template, sources, links, project)
add_logo(project, output_dir)
add_css(css, output_dir)
add_index(index, output_dir)
generate_ddoc(sources, output_dir, ddoc_template, ddoc_line + " " + ddoc_template);
os.remove(ddoc_template)
except Exception as error:
print("Error during documentation generation:", error)
if __name__ == '__main__':
main()