From: Teemu Murtola Date: Wed, 3 Jun 2015 10:54:56 +0000 (+0300) Subject: Improve user guide text for command line interface X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=commitdiff_plain;h=3d2aece877a87a8ec06c8dd37b19aaa88a8a43a7;p=alexxy%2Fgromacs.git Improve user guide text for command line interface - Restructure the tools.rst to have all the content on a single page. - Correct inaccuracies in the information about common options and general behavior, and extend the text to cover more cases. - Include the list of common options on the HTML pages (somewhat ugly still). - Restructure the Sphinx input for easier management and understandability: all pages generated from the gmx binary is now under onlinehelp/, and all rst fragments (whether generated or not) are under fragments/ to make it easy to apply the same rules to all of them. Change-Id: I2d55281bfba7dc781afcc2b09a9fef843730de5f --- diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index f2a3809d31..2c2c7c000e 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -109,7 +109,6 @@ if (SPHINX_FOUND) dev-manual/index.rst dev-manual/codelayout.rst dev-manual/doxygen.rst - dev-manual/doxygen-links.rst dev-manual/formatting.rst dev-manual/gmxtree.rst dev-manual/includestyle.rst @@ -119,6 +118,7 @@ if (SPHINX_FOUND) dev-manual/testutils.rst dev-manual/tools.rst dev-manual/uncrustify.rst + fragments/doxygen-links.rst install-guide/index.rst user-guide/index.rst user-guide/getting-started.rst @@ -141,8 +141,11 @@ if (SPHINX_FOUND) ${SPHINX_INPUT_DIR}/*.rst) list(REMOVE_ITEM _obsolete_sources ${SPHINX_SOURCE_FILES}) foreach(_file ${_obsolete_sources}) - # Skip generated files. - if (NOT _file MATCHES "^(programs/.*|man/bytopic)\\.rst$") + # Skip generated files in onlinehelp/, and fragments. + # The latter do not cause issues with obsolete files, as they + # are not considered as Sphinx input files, but will only be + # included using an explicit .. include::. + if (NOT _file MATCHES "^(onlinehelp|fragments)/.*\\.rst$") message(STATUS "Removing obsolete Sphinx input ${_file}") file(REMOVE ${SPHINX_INPUT_DIR}/${_file}) endif() @@ -173,8 +176,7 @@ if (SPHINX_FOUND) DEPENDS ${SPHINX_INPUT_FILES}) # TODO: Make this remove obsolete .rst files. gmx_add_custom_output_target(sphinx-programs OUTPUT STAMP - COMMAND ${CMAKE_COMMAND} -E make_directory programs - COMMAND ${CMAKE_COMMAND} -E make_directory man + COMMAND ${CMAKE_COMMAND} -E make_directory onlinehelp COMMAND gmx -quiet help -export rst DEPENDS gmx WORKING_DIRECTORY ${SPHINX_INPUT_DIR} diff --git a/docs/conf.py b/docs/conf.py index 8c903fcba6..f3d8830df9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -109,11 +109,9 @@ release = gmx_version_string_full # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['dev-manual/doxygen-links.rst'] +exclude_patterns = ['fragments'] if not tags.has('do_man'): exclude_patterns += ['man'] -else: - exclude_patterns += ['man/bytopic.rst'] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/dev-manual/doxygen.rst b/docs/dev-manual/doxygen.rst index 6d2429b0dc..e24b4244b9 100644 --- a/docs/dev-manual/doxygen.rst +++ b/docs/dev-manual/doxygen.rst @@ -808,4 +808,4 @@ documented mostly along these guidelines. Some comments in ``src/gromacs/selection/`` (in particular, any C-like code) predate the introduction of these guidelines, so those are not the best examples. -.. include:: doxygen-links.rst +.. include:: /fragments/doxygen-links.rst diff --git a/docs/dev-manual/gmxtree.rst b/docs/dev-manual/gmxtree.rst index e2b624fb4b..c942b6d99a 100644 --- a/docs/dev-manual/gmxtree.rst +++ b/docs/dev-manual/gmxtree.rst @@ -236,4 +236,4 @@ white Each edge signifies an include dependency; there is no additional information currently included. -.. include:: doxygen-links.rst +.. include:: /fragments/doxygen-links.rst diff --git a/docs/dev-manual/testutils.rst b/docs/dev-manual/testutils.rst index dadea148dd..5e9536e34d 100644 --- a/docs/dev-manual/testutils.rst +++ b/docs/dev-manual/testutils.rst @@ -196,4 +196,4 @@ Here are some things to keep in mind when working with the unit tests: .. _Google Test Primer: http://code.google.com/p/googletest/wiki/V1_7_Primer .. _Google Mock: http://code.google.com/p/googlemock/ -.. include:: doxygen-links.rst +.. include:: /fragments/doxygen-links.rst diff --git a/docs/dev-manual/tools.rst b/docs/dev-manual/tools.rst index 46fde62b16..855202aaff 100644 --- a/docs/dev-manual/tools.rst +++ b/docs/dev-manual/tools.rst @@ -259,4 +259,4 @@ documentation exported from source files __ doxygen-page-wrapperbinary_ -.. include:: doxygen-links.rst +.. include:: /fragments/doxygen-links.rst diff --git a/docs/dev-manual/doxygen-links.rst b/docs/fragments/doxygen-links.rst similarity index 100% rename from docs/dev-manual/doxygen-links.rst rename to docs/fragments/doxygen-links.rst diff --git a/docs/user-guide/tools.rst b/docs/user-guide/tools.rst index ad3755ac6e..4f193f3abb 100644 --- a/docs/user-guide/tools.rst +++ b/docs/user-guide/tools.rst @@ -1,69 +1,108 @@ -Command-line tools -================== - -|Gromacs| includes many tools for preparing, running and analysing -molecular dynamics simulations. These are all structured as part of the -gmx wrapper binary, and invoked with commands like :ref:`gmx grompp`. -:ref:`mdrun ` is the only other binary that -:ref:`can be built `; in the normal -build it can be run with ``gmx mdrun``. Documentation for these can -be found at the links below: - -.. toctree:: - - /programs/byname - /programs/bytopic - - /programs/selections +Command-line reference +====================== .. toctree:: :hidden: :glob: - /programs/gmx-* - -Common options and behaviour ----------------------------- - -Optional files are not used unless the option is set, in contrast to -non-optional files, where the default file name is used when the option is -not set. - -All |Gromacs| tools will accept file options without a file extension or -filename being specified. In such cases the default filenames will be -used. With multiple input file types, such as generic structure format, -the directory will be searched for files of each type with the supplied -or default name. When no such file is found, or with output files the -first file type will be used. + /onlinehelp/gmx + /onlinehelp/gmx-* -All |Gromacs| tools check if the command line options are valid. If this -is not the case, the program will be halted. - -All |Gromacs| tools have 3 hidden options: - -+-------------------+--------+---------------+-------------------------------------------------+ -| option | type | default | description | -+===================+========+===============+=================================================+ -| ``-[no]hidden`` | bool | \[``yes``\] | \[hidden\] Print description for hidden options | -+-------------------+--------+---------------+-------------------------------------------------+ -| ``-[no]quiet`` | bool | \[``no``\] | \[hidden\] Do not print help info | -+-------------------+--------+---------------+-------------------------------------------------+ -| ``-[no]debug`` | bool | \[``no``\] | \[hidden\] Write file with debug information | -+-------------------+--------+---------------+-------------------------------------------------+ - -Many tools accept enumerated options (enum), which should be used with -one of the arguments listed in the option description. The argument may -be abbreviated, and the first match to the shortest argument in the list -will be selected. - -Many tools also use options that may accept a vector of values. Either 1 -or 3 parameters can be supplied; when only one parameter is supplied the -two other values are also set to this value. +|Gromacs| includes many tools for preparing, running and analysing +molecular dynamics simulations. These are all structured as part of a single +:command:`gmx` wrapper binary, and invoked with commands like :command:`gmx grompp`. +:ref:`mdrun ` is the only other binary that +:ref:`can be built `; in the normal +build it can be run with :command:`gmx mdrun`. Documentation for these can +be found at the respective sections below, as well as on man pages (e.g., +:manpage:`gmx-grompp(1)`) and with :samp:`gmx help {command}` or +:samp:`gmx {command} -h`. + +Command-line interface and conventions +-------------------------------------- + +All |Gromacs| commands require an option before any arguments (i.e., all +command-line arguments need to be preceded by an argument starting with a +dash, and values not starting with a dash are arguments to the preceding +option). Most options, except for boolean flags, expect an argument (or +multiple in some cases) after the option name. +The argument must be a separate command-line argument, i.e., separated by +space, as in ``-f traj.xtc``. If more than one argument needs to be given to +an option, they should be similarly separated from each other. +Some options also have default arguments, i.e., just specifying the option +without any argument uses the default argument. +If an option is not specified at all, a default value is used; in the case of +optional files, the default might be not to use that file (see below). + +All |Gromacs| command options start with a single dash, whether they are +single- or multiple-letter options. However, two dashes are also recognized +(starting from 5.1). + +In addition to command-specific options, some options are handled by the +:command:`gmx` wrapper, and can be specified for any command. See +:doc:`wrapper binary help ` for the list of such options. +These options are recognized both before the command name (e.g., +:command:`gmx -quiet grompp`) as well as after the command name (e.g., +:command:`gmx grompp -quiet`). +There is also a ``-hidden`` option that can be specified in combination with +``-h`` to show help for advanced/developer-targeted options. + +Most analysis commands can process a trajectory with fewer atoms than the +run input or structure file, but only if the trajectory consists of the +first *n* atoms of the run input or structure file. + +Handling specific types of command-line options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +boolean options + Boolean flags can be specified like ``-pbc`` and negated like ``-nopbc``. + It is also possible to use an explicit value like ``-pbc no`` and + ``-pbc yes``. +file name options + Options that accept files names have features that support using default file + names (where the default file name is specific to that option): + + * If a required option is not set, the default is used. + * If an option is marked optional, the file is not used unless the option + is set (or other conditions make the file required). + * If an option is set, and no file name is provided, the default is used. + + All such options will accept file names without a file extension. + The extension is automatically appended in such a case. + When multiple input formats are accepted, such as a generic structure format, + the directory will be searched for files of each type with the supplied or + default name. When no file with a recognized extension is found, an error is given. + For output files with multiple formats, a default file type will be used. + + Some file formats can also be read from compressed (:file:`.Z` or + :file:`.gz`) formats. +enum options + Enumerated options (enum) should be used with one of the arguments listed in + the option description. The argument may be abbreviated, and the first match + to the shortest argument in the list will be selected. +vector options + Some options accept a vector of values. Either 1 or 3 parameters can be + supplied; when only one parameter is supplied the two other values are also + set to this value. +selection options + See :doc:`/onlinehelp/selections`. + +Commands by name +---------------- + +.. include:: /fragments/byname.rst + +Commands by topic +----------------- + +.. include:: /fragments/bytopic.rst + +Special topics +-------------- + +The information in these topics is also accessible through +:samp:`gmx help {topic}` on the command line. -All |Gromacs| tools can read compressed (``*.Z``) or g-zipped (``*.gz``) -files. There might be a problem with reading compressed [.tng] or [.xtc] -files, but these will not compress very well anyway. +.. toctree:: -Most |Gromacs| tools can process a trajectory with fewer atoms than the -run input or structure file, but only if the trajectory consists of the -first n atoms of the run input or structure file. + /onlinehelp/selections diff --git a/src/gromacs/commandline/cmdlinehelpmodule.cpp b/src/gromacs/commandline/cmdlinehelpmodule.cpp index db58fec104..bc883a0849 100644 --- a/src/gromacs/commandline/cmdlinehelpmodule.cpp +++ b/src/gromacs/commandline/cmdlinehelpmodule.cpp @@ -304,13 +304,14 @@ void RootHelpTopic::writeHelp(const HelpWriterContext &context) const } else { + // TODO: This should not really end up on the HTML page. context.writeTitle(formatString("%s commands", helpModule_.binaryName_.c_str())); context.writeTextBlock( "The following commands are available. Please refer to their " "individual man pages or [TT][PROGRAM] help [tt] " "for further details."); context.writeTextBlock(""); - context.writeTextBlock(".. include:: /man/bytopic.rst"); + context.writeTextBlock(".. include:: /fragments/bytopic-man.rst"); } } @@ -537,9 +538,10 @@ HelpExportReStructuredText::HelpExportReStructuredText( void HelpExportReStructuredText::startModuleExport() { indexFile_.reset( - new File(outputRedirector_->openFileForWriting("programs/byname.rst"))); - indexFile_->writeLine("Tools by Name"); - indexFile_->writeLine("============="); + new File(outputRedirector_->openFileForWriting("fragments/byname.rst"))); + indexFile_->writeLine(formatString("* :doc:`%s ` - %s", + binaryName_.c_str(), binaryName_.c_str(), + RootHelpText::title)); manPagesFile_.reset( new File(outputRedirector_->openFileForWriting("conf-man.py"))); manPagesFile_->writeLine("man_pages = ["); @@ -552,7 +554,7 @@ void HelpExportReStructuredText::exportModuleHelp( { // TODO: Ideally, the file would only be touched if it really changes. // This would make Sphinx reruns much faster. - File file(outputRedirector_->openFileForWriting("programs/" + tag + ".rst")); + File file(outputRedirector_->openFileForWriting("onlinehelp/" + tag + ".rst")); file.writeLine(formatString(".. _%s:", displayName.c_str())); if (0 == displayName.compare(binaryName_ + " mdrun")) { @@ -578,7 +580,7 @@ void HelpExportReStructuredText::exportModuleHelp( file.writeLine(" More information about |Gromacs| is available at ."); file.close(); - indexFile_->writeLine(formatString("* :doc:`%s <%s>` - %s", + indexFile_->writeLine(formatString("* :doc:`%s ` - %s", displayName.c_str(), tag.c_str(), module.shortDescription())); manPagesFile_->writeLine( @@ -603,11 +605,9 @@ void HelpExportReStructuredText::finishModuleExport() void HelpExportReStructuredText::startModuleGroupExport() { indexFile_.reset( - new File(outputRedirector_->openFileForWriting("programs/bytopic.rst"))); - indexFile_->writeLine("Tools by Topic"); - indexFile_->writeLine("=============="); + new File(outputRedirector_->openFileForWriting("fragments/bytopic.rst"))); manPagesFile_.reset( - new File(outputRedirector_->openFileForWriting("man/bytopic.rst"))); + new File(outputRedirector_->openFileForWriting("fragments/bytopic-man.rst"))); } void HelpExportReStructuredText::exportModuleGroup( @@ -615,7 +615,7 @@ void HelpExportReStructuredText::exportModuleGroup( const ModuleGroupContents &modules) { indexFile_->writeLine(title); - indexFile_->writeLine(std::string(std::strlen(title), '-')); + indexFile_->writeLine(std::string(std::strlen(title), '^')); manPagesFile_->writeLine(title); manPagesFile_->writeLine(std::string(std::strlen(title), '^')); @@ -630,7 +630,7 @@ void HelpExportReStructuredText::exportModuleGroup( GMX_RELEASE_ASSERT(dashPos != std::string::npos, "There should always be at least one dash in the tag"); displayName[dashPos] = ' '; - indexFile_->writeLine(formatString("| :doc:`%s <%s>` - %s", + indexFile_->writeLine(formatString(":doc:`%s `\n %s", displayName.c_str(), tag.c_str(), module->second)); manPagesFile_->writeLine(formatString(":manpage:`%s(1)`\n %s", @@ -651,14 +651,9 @@ void HelpExportReStructuredText::finishModuleGroupExport() void HelpExportReStructuredText::exportTopic(const HelpTopicInterface &topic) { - const std::string path("programs/" + std::string(topic.name()) + ".rst"); + const std::string path("onlinehelp/" + std::string(topic.name()) + ".rst"); File file(outputRedirector_->openFileForWriting(path)); HelpWriterContext context(&file, eHelpOutputFormat_Rst, &links_); - if (topic.name() == binaryName_) - { - context.writeTextBlock(":orphan:"); - context.writeTextBlock(""); - } HelpManager manager(topic, context); manager.writeCurrentTopic(); } diff --git a/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml b/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml index dbb0ffa7ca..2f4103fdcc 100644 --- a/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml +++ b/src/gromacs/commandline/tests/refdata/CommandLineHelpModuleTest_ExportsHelp.xml @@ -1,12 +1,11 @@ - ` - Print help information -* :doc:`test module ` - First module -* :doc:`test other ` - Second module + ` - molecular dynamics simulation suite +* :doc:`test help ` - Print help information +* :doc:`test module ` - First module +* :doc:`test other ` - Second module ]]> - . ]]> - . ]]> - . ]]> - ` - First module +^^^^^^^ +:doc:`test module ` + First module Group 2 -------- -| :doc:`test other ` - Second module +^^^^^^^ +:doc:`test other ` + Second module ]]> - - - - `` for further details. -.. include:: /man/bytopic.rst +.. include:: /fragments/bytopic-man.rst ]]>