Commit 293f3185 authored by Matthieu Muffato's avatar Matthieu Muffato
Browse files

Also regenerate the scripts documentation with a Sphinx extension

parent 90d54a62
_build
*.pyc
appendix/scripts
......@@ -8,9 +8,9 @@ Execution
.. toctree::
:titlesonly:
scripts/beekeeper.rst
scripts/init_pipeline.rst
scripts/seed_pipeline.rst
scripts/beekeeper
scripts/init_pipeline
scripts/seed_pipeline
Debugging
~~~~~~~~~
......@@ -18,11 +18,11 @@ Debugging
.. toctree::
:titlesonly:
scripts/db_cmd.rst
scripts/hoover_pipeline.rst
scripts/runWorker.rst
scripts/standaloneJob.rst
scripts/tweak_pipeline.rst
scripts/db_cmd
scripts/hoover_pipeline
scripts/runWorker
scripts/standaloneJob
scripts/tweak_pipeline
Reporting
......@@ -31,8 +31,8 @@ Reporting
.. toctree::
:titlesonly:
scripts/generate_graph.rst
scripts/generate_timeline.rst
scripts/load_resource_usage.rst
scripts/visualize_jobs.rst
scripts/generate_graph
scripts/generate_timeline
scripts/load_resource_usage
scripts/visualize_jobs
.. script_documentation:: beekeeper
.. script_documentation:: db_cmd
.. script_documentation:: generate_graph
.. script_documentation:: generate_timeline
.. script_documentation:: hoover_pipeline
.. script_documentation:: init_pipeline
.. script_documentation:: load_resource_usage
.. script_documentation:: runWorker
.. script_documentation:: seed_pipeline
.. script_documentation:: standaloneJob
.. script_documentation:: tweak_pipeline
.. script_documentation:: visualize_jobs
......@@ -15,11 +15,9 @@ def setup_if_needed():
os.environ["ENSEMBL_CVS_ROOT_DIR"] # Will raise an error if missing
os.environ["EHIVE_ROOT_DIR"] = os.path.join(os.environ["PWD"], os.path.pardir)
os.environ["PERL5LIB"] = os.path.join(os.environ["EHIVE_ROOT_DIR"], "modules") + os.path.pathsep + os.environ["PERL5LIB"]
mkdoc_path = os.path.join(os.environ["EHIVE_ROOT_DIR"], "scripts", "dev", "make_docs.pl")
mkdoxygen_path = os.path.join(os.environ["EHIVE_ROOT_DIR"], "scripts", "dev", "make_doxygen.pl")
# Only run doxygen if it's missing
doxygen_target = os.path.join(os.environ["EHIVE_ROOT_DIR"], "docs", "_build", "doxygen")
if (os.environ.get("READTHEDOCS", None) == "True") or any(not os.path.exists(os.path.join(doxygen_target, _)) for _ in ["perl", "python3", "java"]):
subprocess.check_call([mkdoc_path, "-no_script_docs"]) # i.e. run doxygen only
# always run the rest
subprocess.check_call([mkdoc_path, "-no_doxygen"]) # i.e. run everything but doxygen
subprocess.check_call([mkdoxygen_path])
......@@ -85,7 +85,22 @@ class SchemaDocumentation(IncludeCommand):
command.extend( ['--intro', self.options['intro'].replace('$EHIVE_ROOT_DIR', os.environ["EHIVE_ROOT_DIR"])] )
return command
class ScriptDocumentation(IncludeCommand):
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = False
option_spec = {}
def get_command(self):
script_name = self.arguments[0]
script_path = os.path.join(os.environ["EHIVE_ROOT_DIR"], "scripts", script_name+".pl")
self.state.document.settings.record_dependencies.add(script_path)
# If the command becomes too tricky, we can still decide to implement get_content() instead
command = '''awk 'BEGIN{p=1} $0 ~ /^=head/ {if (($2 == "NAME") || ($2 == "LICENSE") || ($2 == "CONTACT")) {p=0} else {p=1}} p {print}' %s | pod2html --noindex --title=%s | pandoc --standalone --base-header-level=2 -f html -t rst | sed '/^--/ s/\\\//g' ''' % (script_path, script_name)
return command
def setup(app):
app.add_directive('schema_documentation', SchemaDocumentation)
app.add_directive('script_documentation', ScriptDocumentation)
......@@ -25,51 +25,10 @@ main();
sub main {
my ($no_script_docs, $no_doxygen);
GetOptions(
'no_script_docs' => \$no_script_docs,
'no_doxygen' => \$no_doxygen,
) or die "Error in command line arguments\n";
if (@ARGV) {
die "ERROR: There are invalid arguments on the command-line: ". join(" ", @ARGV). "\n";
}
generate_docs_scripts() unless($no_script_docs);
unless($no_doxygen) {
generate_docs_doxygen_perl();
generate_docs_doxygen_python();
generate_docs_doxygen_java();
}
}
sub generate_docs_scripts {
my $target_dir = "$ehrd/docs/appendix/scripts";
print "Regenerating $target_dir...\n\n";
my @cmds = (
"rm -rf $target_dir",
"mkdir $target_dir",
);
opendir( my $script_dir, "$ehrd/scripts") || die "Can't opendir $ehrd/scripts: $!";
foreach my $plname ( readdir($script_dir) ) {
if( (-f "$ehrd/scripts/$plname") && $plname=~/^(\w+)\.pl$/) {
my $rstname = $1.'.rst';
push @cmds, "awk 'BEGIN{p=1} \$0 ~ /^=head/ {if ((\$2 == \"NAME\") || (\$2 == \"LICENSE\") || (\$2 == \"CONTACT\")) {p=0} else {p=1}} p {print}' $ehrd/scripts/$plname | pod2html --noindex --title=$plname | pandoc --standalone --base-header-level=2 -f html -t rst -o $target_dir/$rstname";
push @cmds, ['sed', '-i', q{/^--/ s/\\\//g}, "$target_dir/$rstname"];
}
}
closedir($script_dir);
push @cmds, "rm pod2htm?.tmp"; # clean up after pod2html
foreach my $cmd (@cmds) {
print "Running the following command:\n\t$cmd\n\n";
system( ref($cmd) ? @$cmd : $cmd ) && die "Command failed\n";
}
}
......@@ -226,7 +185,7 @@ make_docs.pl
=head1 DESCRIPTION
An internal eHive script for regenerating the documentation both in docs/scripts (using pod2html) and docs/doxygen (using doxygen).
An internal eHive script for regenerating the Doxygen documentation.
=head1 LICENSE
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment