- 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
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
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
${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()
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}
# 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.
``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
Each edge signifies an include dependency; there is no additional information
currently included.
-.. include:: doxygen-links.rst
+.. include:: /fragments/doxygen-links.rst
.. _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
__ doxygen-page-wrapperbinary_
-.. include:: doxygen-links.rst
+.. include:: /fragments/doxygen-links.rst
-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 <gmx mdrun>` is the only other binary that
-:ref:`can be built <building just the mdrun binary>`; 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 <gmx mdrun>` is the only other binary that
+:ref:`can be built <building just the mdrun binary>`; 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 </onlinehelp/gmx>` 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
}
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 <command>[tt] "
"for further details.");
context.writeTextBlock("");
- context.writeTextBlock(".. include:: /man/bytopic.rst");
+ context.writeTextBlock(".. include:: /fragments/bytopic-man.rst");
}
}
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 </onlinehelp/%s>` - %s",
+ binaryName_.c_str(), binaryName_.c_str(),
+ RootHelpText::title));
manPagesFile_.reset(
new File(outputRedirector_->openFileForWriting("conf-man.py")));
manPagesFile_->writeLine("man_pages = [");
{
// 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"))
{
file.writeLine(" More information about |Gromacs| is available at <http://www.gromacs.org/>.");
file.close();
- indexFile_->writeLine(formatString("* :doc:`%s <%s>` - %s",
+ indexFile_->writeLine(formatString("* :doc:`%s </onlinehelp/%s>` - %s",
displayName.c_str(), tag.c_str(),
module.shortDescription()));
manPagesFile_->writeLine(
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(
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), '^'));
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 </onlinehelp/%s>`\n %s",
displayName.c_str(), tag.c_str(),
module->second));
manPagesFile_->writeLine(formatString(":manpage:`%s(1)`\n %s",
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();
}
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="referencedata.xsl"?>
<ReferenceData>
- <String Name="programs/byname.rst"><![CDATA[
-Tools by Name
-=============
-* :doc:`test help <test-help>` - Print help information
-* :doc:`test module <test-module>` - First module
-* :doc:`test other <test-other>` - Second module
+ <String Name="fragments/byname.rst"><![CDATA[
+* :doc:`test </onlinehelp/test>` - molecular dynamics simulation suite
+* :doc:`test help </onlinehelp/test-help>` - Print help information
+* :doc:`test module </onlinehelp/test-module>` - First module
+* :doc:`test other </onlinehelp/test-other>` - Second module
]]></String>
<String Name="conf-man.py"><![CDATA[
man_pages = [
('programs/test', 'test', 'molecular dynamics simulation suite', '', 1)
]
]]></String>
- <String Name="programs/test-help.rst"><![CDATA[
+ <String Name="onlinehelp/test-help.rst"><![CDATA[
.. _test help:
test help
More information about |Gromacs| is available at <http://www.gromacs.org/>.
]]></String>
- <String Name="programs/test-module.rst"><![CDATA[
+ <String Name="onlinehelp/test-module.rst"><![CDATA[
.. _test module:
test module
More information about |Gromacs| is available at <http://www.gromacs.org/>.
]]></String>
- <String Name="programs/test-other.rst"><![CDATA[
+ <String Name="onlinehelp/test-other.rst"><![CDATA[
.. _test other:
test other
More information about |Gromacs| is available at <http://www.gromacs.org/>.
]]></String>
- <String Name="programs/bytopic.rst"><![CDATA[
-Tools by Topic
-==============
+ <String Name="fragments/bytopic.rst"><![CDATA[
Group 1
--------
-| :doc:`test module <test-module>` - First module
+^^^^^^^
+:doc:`test module </onlinehelp/test-module>`
+ First module
Group 2
--------
-| :doc:`test other <test-other>` - Second module
+^^^^^^^
+:doc:`test other </onlinehelp/test-other>`
+ Second module
]]></String>
- <String Name="man/bytopic.rst"><![CDATA[
+ <String Name="fragments/bytopic-man.rst"><![CDATA[
Group 1
^^^^^^^
:manpage:`test-module(1)`
Second module
]]></String>
- <String Name="programs/topic1.rst"><![CDATA[
+ <String Name="onlinehelp/topic1.rst"><![CDATA[
Test topic
==========
Help text
---------------------
Sub text
]]></String>
- <String Name="programs/topic2.rst"><![CDATA[
+ <String Name="onlinehelp/topic2.rst"><![CDATA[
Another topic
=============
Help text
]]></String>
- <String Name="programs/test.rst"><![CDATA[
-:orphan:
-
+ <String Name="onlinehelp/test.rst"><![CDATA[
molecular dynamics simulation suite
===================================
Synopsis
-------------
The following commands are available. Please refer to their individual man pages or ``commandline-test help <command>`` for further details.
-.. include:: /man/bytopic.rst
+.. include:: /fragments/bytopic-man.rst
]]></String>
</ReferenceData>
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff