Skip to content

Documentation Standards

Jump to bottom Edit New page
GSStnb edited this page Mar 30, 2020 · 29 revisions

Note: The standards are specifically for document contributions via GitHub using the "restructuredstext" (markup language supported by "Read the Docs", RtD). The RtD LibreCAD doc site has configured to in a particular way, so following these standards is important. If these standards are not maintained it could break the site or make it more difficult to support revisions.

Structure / Layout

  • The structure (layout / sections) of the site have been established. New sub-sections would need to fall into one of the existing top-level sections (About, Getting started, etc). If a new section is required, it can be discussed on the forum or on Zulip chat. The current structure is:
   - (root) /             (Base directory for all documentation files and RtD configuration.)
      - about/            ("About" section of the User Manual.)
      - appx/             ("Appendics" section of the User Manual.)
      - _build/           (RtD directory - do not alter / delete.)
      - getstart/         ("Getting Started" section of the User Manual.)
      - guides/           ("About" section of the User Manual.)
      - images/           (Screen captures and other images.)
         - fonts/         (Screen captures of all the LibreCAD standard fonts.)
         - hatch/         (Screen captures of all the LibreCAD standard hatches patterns.)
         - icons/         (The LibreCAD icons from the source code.)
         - toolOptions/   (Screen captures of the "Tool Options" toolbars.)
      - ref               ("Reference" section of the User Manual.)
      - _static           (RtD directory - do not alter / delete.)
      - _template         (RtD directory - do not alter / delete.)

Content

Defining Headings / Levels

  • Each top-level section is in its own directory that contains a sub-index (index.rst). The top-level section and the sub-index combines to form the menu structure seen on the left side of the web page and index in the other forms (epub, pdf).
  • Level 1 sections (Drawing Setup, Blocks, ...) are contained in a single restructuredtext file (.rst). These are linked to the index.rst file. Each file contains:
    • a label identifying the version of LibreCAD (.. User Manual, LibreCAD v2.2.x)
    • a section heading underlined with equal signs (====). Note: There can be only one Level 1 section heading per file and it needs to be at the top of the file.
    • a label preceeding the section heading (..section-name:)
  • Level 2 sub-sections (Scale, Attributes, ... under Drawing Setup) are underlined with dashes (-----). These also appear in the menu structure.
    • a label preceeding the sub-section heading (..section-name:)
  • Level 3 sub-sections (Architect’s Scale (SI), ... under Scale) are underlined with tildes (~~~~~). These are the bottom level of the menu structure.
  • Level 4 sub-sections are underlined with grave accent (``````). These do not appear in the menu structure.
  • If additional sub-sections are required, underlined with caret (^^^^^), plus (+++++) and then hash (#####). These do not appear in the menu structure.

Page Width

The page width inherited from RtD / Sphinx is 800 px. All content needs to fit within this limitation. Left and right margins are 16 pixels, reducing the effecting content are to 768px pixels.

Images - Screen Captures

  • Screen captures are created from a default install of LibreCAD to maintain consistency as that is what everyone will start with.
    • A full screen capture is from a screen size of 1280x960 as it provides an appropriate resolution and aspect ratio for both the on-line version and when printing.
      • Images need to be scaled to fit (~700px).
    • Use LC's default colors for the "Graphic Colors" (Snap Indicator, Grid Color, etc.)
      • Use 85% grey (#d9d9d9) for the drawing window "Background" instead of the default "Black" as it provides better images on-line and for printing.
      • Change the background color on the "Appearance" tab of the "Application Preferences" dialog. Select "Options" -> "Application Preferences" on the menubar.
    • Screen captures and drawing images are to be pngs.
      • When possible, native resolution should be used to avoid the need to scale.
      • When greater detail is required, larger images can be used and scaled accordingly. Images are be 'zoomed' when clicked on.
    • Use the svg icons when possible (png when there is no svg equivalent).
    • All images go in the "images" directory or sub-directories (see structure above).

Images - Icons

  • Icons embedded in text are to have a height of 18px and a prorportional width (typ. 18 px).
  • Icons in tables are to be 24px in height and a prorportional width (typ. 24 px).

Images - Illustrations

  • Illustration are to be pngs.
  • Background color for illustrations is white. Object color is black and text is dark green (color code to follow).

Tables

  • Tables are typically formed using the "csv" method. Complex tables are formed using the gridline method (tedious at best, but more flexible - and problematic).
  • The table require the ":class: table-fix-width" directive, otherwise the table do not appear correctly in HTML.

Lists

  • Bullet list use a hyphen "-". Bulleted list are for non-sequential list.
  • Numbered list use a hash mark followed by a period "#.". The hash mark auto numbers the list. Numbered lists are for instructions / step.

Menus, Dialogue Labels and Other

  • Menu paths are shown in bold and levels are separated with -> (dash + greater than sign), eg. File -> New.
  • Dialogue box titles are shown in bold with matching case.
  • Dialogue box labels are enclosed in quotes " " with matching case.
  • Tab titles are enclosed in quotes " " with matching case.
  • Button labels are enclosed in quotes " " with matching case.

Keyboard Commands

  • Key presses are designated with the key label enclosed with square parentheses: [ ].
  • Key combinations are shown with a "+" between keys, e.g. [Ctrl]+[C].

Linking

  • Links within the text can be included to navigate the manual:
    • Internal links can be embedded in the text, e.g. :ref:`User Guide <guides>`
    • External links should show the complete URL following the text, e.g. `librecad.org <http://librecad.org>`_

NOTE: DO NOT ALTER EXISTING Level 1 or Level 2 SECTION NAMES or LABELS as these are used to create menu items or internal links. Deviating from the standards may break things!!!

See the Resources page for more information and links.

Add a custom footer
Add a custom sidebar
Clone this wiki locally