Manual Update

Revision as of 23:54, 2 November 2016 by MatthewLarsen (talk | contribs)

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

Formatting

GUI Elements are bold Chapter Refs are :ref:`section-label` Other doc names :italics

Labes / Figures

//General section labels
.. _my-label:

Section Title
--------------

This is a reference to section :ref:`my-label`.

// Figures
.. _my-figure:: images/filename.png

    This is the caption

//To reference the figure

We show how to do this in :numref:`Figure %s<my-figure>`.


Other useful directives

.. note::

.. code::

.. image:: filename.png

Sectioning

Chapter
======

Subsubsection
-----------------

Subsubsection
~~~~~~~~~~~

Paragraph
"""""""""""

We can add more if needed.

Instructions from Matt

I have not figured out how to create an account on the wiki page so I am going to try to do this over email. I click on login/create account and all it lets me do is login, which I can’t because I don’t have an account.

I have put the entire manual at: http://mclarsen.com/visit/index.html Sorry this took so long but I had to work through a number of issues.

I have fixed many of the navigation issues and broken up several of the really long sections into multiple files (e.g., Plot and operator types). I have create some python scripts to automatically do this as well as some other tasks related to the markup format.

Please claim a chapter and review it for the following

  • Automatic conversion errors
    • bad bold or random ***s
    • missing figures (the work figure is missing so it will look like “see .” or (see )
    • Identify other categories of errors
  • Identify long pages that should be broken up into smaller files (the script I have will break them up at a specified sectioning level)
  • General usability
    • What is this missing in terms of functionality?
    • Is anything broken or behave unexpectedly?
    • Navigation nesting levels too deep?
    • Anything else you can think of and suggestions.

Here are the manual chapters

  • Intro/index - Mark
  • Plots/index - Eric
  • Operators/index - Eric
  • SavingPrinting/index - Eric
  • VisualizationWindows/index - Eric
  • Subsetting/index - Mark
  • Quantitative/index
  • MakingItPretty/index
  • Animation/index
  • InteractiveTools/index
  • MultipleDatabaseAndWindows/index
  • RemoteVisualization/index
  • Preferences/index
  • Help/index - Cyrus
  • Appendix_A/index - Cyrus
  • Appendix_B/index - Cyrus
  • Appendix_C/index - Cyrus
  • WorkingWithFiles/index - Mark

Eric comments on plots

Plots "Overview" section can probably be removed.

Managing plots

Extra spaces before commas in a few places. "**" errors in the second paragraph.

Creating a plot

Strange paragraph breaks within text twice.

Selecting a plot

Should "Ctrl" and "Shift" key be italic, based on the conventions?

Drawing a plot

"**" errors.

Hiding a plot

"hidden" doesn't have a space after the double quote.

Standard Plot Types

I would change links in the page to only list the plots types and not all the sections under them.

Boundary and FilledBoundary Plots

Changing colors

"**" errors.

Setting point properties

"**" errors.

Contour Plot

Setting contour colors

"**" errors in the second paragraph.

Label Plot

Formatting labels

"**" errors in the third paragraph.

Mesh Plot

Changing the point size

"**" errors.

Pseudocolor Plot

Variable centering

Should "zone-centered" and "node-centered" be italic, based on the conventions?

Limits

"**" errors in the second paragraph.

Scaling the data

"**" errors.

Changing the point size

"**" errors.

Scatter Plot

"Appearance tab" line above "Setting point attributes" looks odd.

Streamline Plot

Move some of the content to the Streamline operator.

Setting the streamline source

I saw "(see )" in the third, fourth, fifth and sixth paragraphs.

Setting streamline appearance

"**" errors in the second paragraph.

Surface Plot

Scaling the data

"**" errors.

Vector Plot

Setting vector color

"**" errors in the first paragraph.

Heads on the vector glyph

"**" errors.

Tails on the vector glyph

"**" errors.

Volume Plot

Strange paragraph breaks in the last paragraph.

Eric's comments on operators

Should probably remove the overview section.

Managing operators

Extra spaces before commas in a few places. "**" errors in the third paragraph.

Adding an operator

"(see )" in the third paragraph.

Operator Types

The tables first column is much wider than the rest for no good reason.

The links listing the operators shows the amount of depth I would like to see for the plots.

For the actual operators I saw more errors of the type that I had already seen. I didn't see any reason to list them all. We might as well fix those and other issues in a fixing pass.

Eric's comments on saving and printing

The links listing the sections are one level deeper than I would prefer.

Should probably move the overview to the section where we list the links.

Saving the visualization window

Not sure why doing italics instead of bold in many cases. "**" errors scattered throughout.

Saving movies

I see a page number reference. There are paragraph breaks in the middle of a sentence errors. There are "(See Figure )" with no reference errors. There are "Figure " with no reference errors. "**" errors scattered throughout.

Printing

There are "(See Figure )" with no reference errors. There are "Figure " with no reference errors.

Eric's comments on visualization windows

The links listing the sections are one level deeper than I would prefer.

Should probably move the overview to the section where we list the links.

Managing vis windows

There are "(see )" with no reference errors. "**" errors scattered throughout.

Using vis windows

"**" errors scattered throughout.

The popup menu and the Toolbar

There are "(see )" with no reference errors "**" errors scattered throughout. There are paragraph breaks in the middle of a sentence errors.