Manual Update

Revision as of 22:53, 27 October 2017 by MatthewLarsen (talk | contribs) (Here is the status of the chapters)

Building Documentation

I have added the rst files to docs/SphynxDocs. This will allow others to manually edit the files as they discover errors.

To build the website locally, you will need python and sphynx. The download links for various platforms are at http://www.sphinx-doc.org/en/stable/install.html

For everyone's convenience, I added a bash script (lc_sphynx_build_command.sh) that will build the docs on the CZ that leverages the installs for conduit's documentation. I'm not sure if the paths are valid on the RZ. This will build the website in the _build directory, and then just open _build/index.html with firefox.

Sphinx Conventions

Line Lengths

Lines should not be longer than 80 characters long so that they don't wrap on an 80 character terminal window.

Chapters

Each chapter name should use title case.

Each chapter should be in a directory, with the directory name using camel case. The name of the directory should match the chapter name if possible. Abbreviations should be minimized.

Each chapter should have an index.rst file with a reference tag at the beginning of the file. These look like the following:

.. _XXX:

where XXX is the name of the directory that contains the chapter. For example, the "Preferences" chapter is contained in the "Preferences" directory and the "index.rst" file would have "XXX" be "Preferences". Note that there is a blank line after the line containing "XXX".

To reference the chapter you would insert

:ref:`XXX`

in the text.

If the chapter has an overview, it should be included in the "index.rst" file.

Sections

Each top level section should be in its own file with the file name using snake case. The file name should match the section name and the capitalization of the file name should match that of the section name. For example, if the section name was "View and data limits", the filename should be View_and_data_limits.

Each top level section should have a reference tag at the beginning of the file where the tag is the same as the section name, including any blanks. Using "View and data limits" as an example again, the section tag would be "View and data limits". Each top level section name must be unique because of the reference tags. This shouldn't be a big issue since you can always change the name of the section to make it unique.

Formatting

GUI elements are bold Chapter refences are :ref:`section-label` Other doc names :italics

When bolding GUI element, the element names should match what is in the GUI and the type of the GUI element should not be bolded. In particular:

area - use "panel"

button

check box

label

list

menu

option

panel - preferable to "area"

radio button

spin box

sub tab

tab

text field

should never be bolded.

For example "3D tab", should have "3D" bolded and "tab" normal.

Figures

To add a figure to the manual, add the following text.

.. _fig-filename:

.. _figure:: images/filename.png
   :width:: 60%
   :align: center

    This is the caption

The first line is the label for the figure. The convention is to give it the same label as the filename with "fig-" prepended to the filename. The second line contains the name of the image. Below the second line are optional lines that control the width and alignment of the image. The third line is the caption for the figure. In general figures should be used in preference to images.

Image label names need to be unique across the manual. I suggest we prepend the chapter directory name to the image name.

Would it be useful to be able to distinguish between gui images and visualization window images from the name? I expect we will have more gui images, so adding an extra string to visualization windows would increase the length of the minimum number of image names. Thoughts are adding "example" at the end of the visualization window image names. Here are some examples for image names in the "MakingItPretty" chapter.

MakingItPretty-ViewAdvanced.png

MakingItPretty-ViewSpecularExample.png

To reference the figure add the following text. The "Figure" text can be arbitrary. The number of the figure is substituted for the "%s".

:numref:`Figure %s <filename>`

A good default image size for visualization windows is 768 x 1024. If it makes sense to use a different aspect ratio to better accommodate the image, the height should be adjusted, maintaining the 1024 width.

For the GUI images, using the default window size is a good starting point. Once we have a first cut at the document we can see how they appear in web and pdf form and come up with conventions at that point.

Images within a section should all be generated on the same operating system initially. Preferably all the images for a single chapter are also generated on the same operating system. When we have automated capturing of GUI windows working we can generate them all on the same operating system.

Other useful directives

.. note::

.. code::

.. image:: filename.png

Sectioning

Here are the conventions for sections.

Chapter - Use Title Case
========================

Subsubsection - Use Title Case
------------------------------

Subsubsection - Use Title Case
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Paragraph - Use normal case
"""""""""""""""""""""""""""

We can add more if needed. All of these characters are valid for sectioning: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

Here is the status of the chapters

  • Intro - Eric
  • WorkingWithFiles - Mark - In progress
  • Plots - Matt - In progress - Matt will check in his changes and then people can sign up for individual plots
    • Boundary and FilledBoundary -- Matt -- done
    • Contour -- Matt -- done
    • Curve -- Kathleen
    • Histogram -- Matt -- images are done, but there is a lot of new functionality and I don't know what it does
    • Label -- Matt -- done
    • Mesh -- Matt -- done
    • Pseudocolor -- Matt -- done
    • Scatter -- Matt -- done
    • Subset -- Matt -- in progress (cannot duplicate the image)
    • Surface - Removed
    • Tensor -- Matt -- done
    • Truecolor -- Matt -- done
    • Vector -- Matt -- done
    • Volume --Matt -- in progress
  • Operators
    • Box -- Kathleen -- done
    • Clip -- Kathleen -- done
    • Cone -- Kathleen -- done
    • Connected Components -- Kathleen -- done
    • Cylinder -- Kathleen -- done
    • Decimate -- Kathleen -- done
    • DeferExpression -- Kathleen -- done
    • Displace -- Kathleen -- done
    • Elevate -- Kathleen -- done
    • ExternalSurface -- Kathleen -- done
    • Index Select -- Kathleen -- done
    • InverseGhostZone -- Kathleen -- done
    • Isosurface -- Kathleen -- done
    • Isovolume -- Kathleen -- done
    • Lineout -- Kathleen
    • Merge -- Kathleen -- done
    • OnionPeel -- Kathleen -- done
    • Project -- Kathleen -- done
    • Reflect -- Kathleen -- done
    • Revolve -- Kathleen -- done
    • Resample -- Kathleen -- done
    • Slice -- Kathleen -- done
    • Smooth -- Kathleen -- done
    • SphereSlice -- Kathleen -- done
    • ThreeSlice -- Kathleen -- done
    • Threshold -- updated previously Matt and Kevin -- Done
    • Transform -- Kathleen -- done
    • Tube -- Kathleen -- done
  • SavingPrinting - Kevin - done
  • VisualizationWindows -
  • Subsetting - Mark
  • Quantitative - Mark - In progress
  • MakingItPretty - Eric - In progress
  • Animation - Kevin - In progress
  • InteractiveTools -
  • MultipleDatabaseAndWindows -
  • ClientServer - Kathleen -- done
  • ComputeEngines - Cyrus -- done
  • Preferences -
  • Help -
  • StartupOptions - Cyrus

Open issues

  • Figure out how to have wide tables display better in html output.
    • There is a way to add manual line breaks to the html output. We can fix the table in section 1.2 using this. We will eliminate the tables in Appendix A.
    • For the expressions and queries table (sections 8.2.3 and 8.3.2) Mark will develop an alternative to a table and we can decide [done].
  • Figures with small images display very large in pdf output.
    • No resolution on this yet.
  • We should have guidelines for images sizes (from Vis windows in particular).
    • Some things to consider, size, aspect ratio, removing unnecessary annotations (e.g. user info)* We need to figure out how to automate generation of GUI images
  • We need to figure out process for automatically compositing figures with multiple images. (e.g. do we use image magic, PIL, etc.)
    • This is a low priority item. Capturing GUI windows is the highest priority and we will focus on that. Kevin will try to prototype something for this.
  • Appendix A on command line options. How can we automatically generate to avoid maintenance issue?
    • We should capture the help output from VisIt. We will rename this chapter "Command line options". Mark will look into this [done].
  • Appendix B on setting up passwordless ssh. This should be in one place. Manual or somewhere else?
    • Move this to the Remote Visualization chapter.
  • Appendix C on installing visit. Should be in one place. Manual or somewhere else?
    • Let's remove this.
  • We need to replace the mechanism that creates our in-visit help from the manual
  • Should include other places for help in intro chapter
    • visitusers.org, tutorials, etc.
    • Maybe statement that tutorials X, Y and Z are best first thing to try to get acquainted with VisIt
  • Need to add veriabage, maybe whole chapter, on licensing
  • move remote vis. chapter up to around 6 or 7
  • Update copyright text
  • We should consider including links from manual to tutorials where appropriate