Difference between revisions of "Manual Update"

(Sectioning)
m
 
(140 intermediate revisions by 7 users not shown)
Line 8: Line 8:
  
 
= Sphinx Conventions =
 
= Sphinx Conventions =
== Formatting==
 
GUI Elements are bold
 
Chapter Refs are :ref:`section-label`
 
Other doc names :italics
 
  
== Labes / Figures ==  
+
== 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:
  
 
<source lang="cpp">
 
<source lang="cpp">
//General section labels
+
.. _XXX:
.. _my-label:
 
  
Section Title
+
</source>
--------------
 
  
This is a reference to section :ref:`my-label`.
+
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".
  
// Figures
+
To reference the chapter you would insert
.. _my-figure:: images/filename.png
 
  
    This is the caption
+
<source lang="cpp">
 +
:ref:`XXX`
 +
</source>
 +
 
 +
in the text.
  
//To reference the figure
+
If the chapter has an overview, it should be included in the "index.rst" file.
  
We show how to do this in :numref:`Figure %s<my-figure>`.
+
== Sections ==
</source>
+
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.
  
== Other useful directives ==
+
== Formatting ==
 +
GUI elements are bold
 +
Chapter refences are :ref:`section-label`
 +
Other doc names :italics
  
<source lang="cpp">
+
When bolding GUI element, the element names should match what is in the GUI and the type of the GUI element should
.. note::
+
not be bolded. In particular:
  
.. code::
+
area - use "panel"
  
.. image:: filename.png
+
button
</source>
 
  
== Sectioning ==
+
check box
Sectioning needs to be consistent throughout the pages in the manual. For example all of these characters are valid for sectioning: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ To be consistent, please use the following:
 
  
<source lang="cpp">
+
label
  
Chapter
+
list
======
 
  
Subsubsection
+
menu
-----------------
 
  
Subsubsection
+
option
~~~~~~~~~~~
 
  
Paragraph
+
panel - preferable to "area"
"""""""""""
 
  
We can add more if needed.
+
radio button
  
</source>
+
spin box
  
= Instructions from Matt =
+
sub tab
  
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.
+
tab
  
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.
+
text field
  
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.
+
should never be bolded.
  
Please claim a chapter and review it for the following
+
For example "3D tab", should have "3D" bolded and "tab" normal.
* 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?
+
== Figures ==
** Is anything broken or behave unexpectedly?
 
** Navigation nesting levels too deep?
 
** Anything else you can think of and suggestions.
 
  
== Here are the manual chapters ==
+
To add a figure to the manual, add the following text.
* 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 ==
+
<source lang="cpp">
 +
.. _fig-filename:
  
Plots "Overview" section can probably be removed.
+
.. _figure:: images/filename.png
 +
  :width:: 60%
 +
  :align: center
  
=== Managing plots ===
+
    This is the caption
Extra spaces before commas in a few places.
+
</source>
"**" 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 ===
+
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.
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 ===
+
Image label names need to be unique across the manual. I suggest we prepend the chapter directory name to the image name.
==== Setting contour colors ====
 
"**" errors in the second paragraph.
 
  
=== Label Plot ===
+
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.
==== Formatting labels ====
 
"**" errors in the third paragraph.
 
  
=== Mesh Plot ===
+
MakingItPretty-ViewAdvanced.png
==== Changing the point size ====
 
"**" errors.
 
  
=== Pseudocolor Plot ===
+
MakingItPretty-ViewSpecularExample.png
==== 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 ===
+
To reference the figure add the following text. The "Figure" text can be arbitrary. The number of the figure is substituted for the "%s".
"Appearance tab" line above "Setting point attributes" looks odd.
 
  
=== Streamline Plot ===
+
<source lang="cpp">
Move some of the content to the Streamline operator.
+
:numref:`Figure %s <filename>`
==== Setting the streamline source ====
+
</source>
I saw "(see )" in the third, fourth, fifth and sixth paragraphs.
 
==== Setting streamline appearance ====
 
"**" errors in the second paragraph.
 
  
=== Surface Plot ===
+
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.
==== Scaling the data ====
 
"**" errors.
 
  
=== Vector Plot ===
+
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.
==== Setting vector color ====
 
"**" errors in the first paragraph.
 
==== Heads on the vector glyph ====
 
"**" errors.
 
==== Tails on the vector glyph ====
 
"**" errors.
 
  
=== Volume Plot ===
+
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.
Strange paragraph breaks in the last paragraph.
 
  
== Eric's comments on operators ==
+
== Other useful directives ==
  
Should probably remove the overview section.
+
<source lang="cpp">
 +
.. note::
  
=== Managing operators ===
+
.. code::
Extra spaces before commas in a few places.
 
"**" errors in the third paragraph.
 
=== Adding an operator ===
 
"(see )" in the third paragraph.
 
  
=== Operator Types ===
+
.. image:: filename.png
The tables first column is much wider than the rest for no good reason.
+
</source>
  
The links listing the operators shows the amount of depth I would like to see for the plots.
+
== Sectioning ==
  
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.
+
Here are the conventions for sections.
  
== Eric's comments on saving and printing ==
+
<source lang="cpp">
  
The links listing the sections are one level deeper than I would prefer.
+
Chapter - Use Title Case
 +
========================
  
Should probably move the overview to the section where we list the links.
+
Subsubsection - Use Title Case
 +
------------------------------
  
=== Saving the visualization window ===
+
Subsubsection - Use Title Case
Not sure why doing italics instead of bold in many cases.
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"**" errors scattered throughout.
 
  
=== Saving movies ===
+
Paragraph - Use normal case
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 ===
+
Subparagraph - Use normal case
There are "(See Figure )" with no reference errors.
+
''''''''''''''''''''''''''''''
There are "Figure " with no reference errors.
 
  
== Eric's comments on visualization windows ==
+
</source>
  
The links listing the sections are one level deeper than I would prefer.
+
We can add more if needed. All of these characters are valid for sectioning: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
  
Should probably move the overview to the section where we list the links.
+
== Here is the status of the chapters ==
 +
* Intro - Eric - done
 +
* WorkingWithFiles - Mark - in progress
 +
* Plots - Eric - done
 +
** Boundary and FilledBoundary -- Matt -- done
 +
** Contour -- Matt -- done
 +
** Curve -- Kathleen -- done
 +
** Histogram -- Matt -- images are done, but there is a lot of new functionality and I don't know what it does (CYRUS will look at)
 +
** Label -- Matt -- done
 +
** Mesh -- Matt -- done
 +
** Pseudocolor -- Matt -- done
 +
** Scatter -- Matt -- done
 +
** Subset -- Matt -- done
 +
** Surface - Removed
 +
** Tensor -- Matt -- done
 +
** Truecolor -- Matt -- done
 +
** Vector -- Matt -- done
 +
** Volume --Matt -- done
 +
* Operators -- Eric - done
 +
** 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 -- done
 +
** 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 -- Kathleen -- done
 +
* Subsetting -- Mark
 +
* Quantitative -- Mark -- in progress
 +
* MakingItPretty - Eric -- done
 +
* Animation -- Kevin - done
 +
* InteractiveTools -- Kathleen -- done
 +
* MultipleDatabaseAndWindows -- Kathleen -- done
 +
* ClientServer -- Kathleen -- done
 +
* ComputeEngines -- Cyrus -- done
 +
* Preferences -- Eric -- done
 +
* Help - Kevin -- done
 +
* StartupOptions -- Cyrus
  
=== Managing vis windows ===
+
= Open issues =
There are "(see )" with no reference errors.
 
"**" errors scattered throughout.
 
  
=== Using vis windows ===
+
* Figure out how to have wide tables display better in html output.
"**" errors scattered throughout.
+
** 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
  
=== The popup menu and the Toolbar ===
+
[[Category: Advanced projects]]
There are "(see )" with no reference errors
 
"**" errors scattered throughout.
 
There are paragraph breaks in the middle of a sentence errors.
 

Latest revision as of 01:08, 27 July 2021

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
"""""""""""""""""""""""""""

Subparagraph - 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 - done
  • WorkingWithFiles - Mark - in progress
  • Plots - Eric - done
    • Boundary and FilledBoundary -- Matt -- done
    • Contour -- Matt -- done
    • Curve -- Kathleen -- done
    • Histogram -- Matt -- images are done, but there is a lot of new functionality and I don't know what it does (CYRUS will look at)
    • Label -- Matt -- done
    • Mesh -- Matt -- done
    • Pseudocolor -- Matt -- done
    • Scatter -- Matt -- done
    • Subset -- Matt -- done
    • Surface - Removed
    • Tensor -- Matt -- done
    • Truecolor -- Matt -- done
    • Vector -- Matt -- done
    • Volume --Matt -- done
  • Operators -- Eric - done
    • 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 -- done
    • 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 -- Kathleen -- done
  • Subsetting -- Mark
  • Quantitative -- Mark -- in progress
  • MakingItPretty - Eric -- done
  • Animation -- Kevin - done
  • InteractiveTools -- Kathleen -- done
  • MultipleDatabaseAndWindows -- Kathleen -- done
  • ClientServer -- Kathleen -- done
  • ComputeEngines -- Cyrus -- done
  • Preferences -- Eric -- done
  • Help - Kevin -- done
  • 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