Styleguide

Secties

Je maakt aparte secties door titels te definieren. Dit doe je door een regel die als titel moet functioneren te onderstrepen. Wij gebruiken de volgende karakters voor het onderstrepen: # = - _ ~.

Dit is een level 0 titel
########################

Dit is een level 1 subtitel
===========================

Dit is een level 2 subtitel
---------------------------

Dit is een level 3 subtitel
___________________________

Dit is een level 4 subtitel
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Het resultaat hiervan is:

Dit is een level 0 titel

Dit is een level 1 subtitel

Dit is een level 2 subtitel

Dit is een level 3 subtitel

Dit is een level 4 subtitel

De regels met deze karakters moeten ten minste net zo lang zijn als de tekst waar het onder staat om er een subtitel van te maken.

Tekst opmaak

Gewone tekst zonder opmaak wordt getoond zoals deze alinea. Gewone enters doen niks. Je kan nieuwe alinea’s beginnen door er een lege regel tussen te doen:

Dit is alinea 1.
Dit is nog steeds alinea 1.

Dit is alinea 2.

Het resultaat hiervan is:

Dit is alinea 1. Dit is nog steeds alinea 1.

Dit is alinea 2.

Als je expliciet toch een enter wilt in de tekst, moet je voor zowel de zin vòòr de enter als de zin ná de enter voorgaan met een pipe en een spatie:

| Dit is alinea 1.
| Dit is nog steeds alinea 1.

Dit is alinea 2.

Het resultaat hiervan is:

Dit is alinea 1.

Dit is nog steeds alinea 1.

Dit is alinea 2.

Verder kan je met sterretjes of backticks (`) extra nadruk geven op teksten:

Door enkele sterretjes om een woord of zin te plaatsen wordt deze *schuingedrukt*.

Door dubbele sterretjes om een woord of zin te plaatsen wordt deze **dikgedrukt**.

Door dubbele backticks om een woord of zin te plaatsen krijgt deze een ``monospaced lettertype, grijze achtergrond en rode tekst``.

Het resultaat hiervan is:

Door enkele sterretjes om een woord of zin te plaatsen wordt deze schuingedrukt.

Door dubbele sterretjes om een woord of zin te plaatsen wordt deze dikgedrukt.

Door dubbele backticks om een woord of zin te plaatsen krijgt deze een monospaced lettertype, grijze achtergrond en rode tekst.

De dubbele backticks zijn mooi om iets letterlijk te benoemen, bijvoorbeeld een aantal karakters zoals bovenin dit document voor het aangeven welke karakters gebruikt kunnen worden voor secties. Of in handleiding voor het verwijzen naar een bepaalde pagina. Bijvoorbeeld: Ga naar Onderhoud >> Stamgegevens >> Afdelingen. Let op: voor menuitems gebruik ik dubbele groter-dan tekens (>>), en voor tabbladen of andere kopjes op een pagina een pijltje (->). Een verwijzing naar de workflow instellingen zou worden: Ga naar Systeem >> Klantinstellingen -> Workflow instellingen.

Vervangingsteken

Als je een woord of zin tussen 2 pipes (|) zet, geef je aan dat deze vervangen moet worden met iets wat later in het document gedefinieerd wordt. Dit is ideaal voor links en plaatjes. Zo kan je in je schrijven een steekwoord gebruiken zonder dat je een link hebt die je zin onderbreekt. Daarnaast heb je ook op 1 plek alle verwijzingen staan zodat het beheer makkelijker is.

Ik gebruik in deze zin een plaatje: |img_sample| en een link: |lnk_sample| met behulp van vervangingstekens.

Onderin het document zijn dan 2 vervangingen gedefinieerd:

.. |img_sample| image:: media/sample.png
.. |lnk_sample| replace:: :ref:`klik hier <styleguide>`

Dit heeft als resultaat:

Ik gebruik in deze zin een plaatje: en een link: klik hier met behulp van vervangingstekens.

Snelkoppelingen

Intern

We linken niet direct naar pagina’s, maar naar ‘labels’. Dit zijn de ‘anchors’ in HTML. Deze kan je overal op de pagina zetten, en een link hiernaar zal dan automatisch naar die plek op de pagina scrollen. Bovenaan deze pagina is het label “styleguide” als volgt gedefinieerd:

.. _styleguide:

Deze zie je niet op de pagina zelf. Let ook op dat de definitie van een label voorgegaan wordt met een underscore. Je kan naar de label verwijzen met een “ref”-directive, om de tekst zelf leesbaar te houden zetten we die wel in een substitution (tussen vervangingstekens).

Als ik op deze manier naar de |lnk_styleguide| link, krijg je dus een link naar de bovenkant van deze pagina.

Met de volgende definitie onderaan het document:

.. |lnk_styleguide| replace:: :ref:`styleguide <styleguide>`

Het resultaat hiervan is:

Als ik op deze manier naar de styleguide link, krijg je dus een link naar de bovenkant van deze pagina.

In de ref-directive zet je eerst de naam die de gebruiker moet zien, en dan tussen de haakjes de naam van het label zonder de underscore.

De label waar je naar wilt linken hoeft niet op de zelfde pagina te staan. Linken naar andere pagina’s werkt dus exact het zelfde:

Ga naar |lnk_styleguide-test|.

Met de volgende definitie onderaan het document:

.. |lnk_styleguide-test| replace:: :ref:`een andere pagina <styleguide-testpagina>`

Het resultaat hiervan is:

Ga naar een andere pagina.

Omdat het linken tussen pagina’s deze labels gebruikt, moeten deze labels over alle pagina’s heen dus wel uniek zijn. Het is dan ook verstandig om de hierarchie van die link in de labelnaam op te nemen. Bijvoorbeeld de link naar de handleiding Leverancier >> Klant aanmaken zou je zo definieren:

.. _leverancier-klant-aanmaken:

Extern

Gewone adressen met protocol zoals http://www.google.com worden automatisch hyperlinks, om dit te voorkomen kan je een backslash (\) voor de url zetten:

Adressen zoals http://www.google.com worden automatisch hyperlinks.

Adressen zoals \http://www.google.com zullen dan gewoon tekst blijven.

Het resultaat hiervan is:

Adressen zoals http://www.google.com worden automatisch hyperlinks

Adressen zoals http://www.google.com zullen dan gewoon tekst blijven.

Voor externe links werkt het met vervangingstekens net iets anders. De substitution heeft er nu een underscore achter:

Dit is een link: |lnk_extern|_. Deze gaat naar een externe website.

Je moet de substitution definieren met enkel de naam die de gebruiker moet zien, en dan ook een expliciete link definieren met het adres:

.. |lnk_extern| replace:: Ecmanage
.. _lnk_extern: https://www.ecmanage.nl/

Het resultaat hiervan is:

Dit is een link: Ecmanage. Deze gaat naar een externe website.

Tabellen

Als ASCII

Tabellen maak je door een tabel in ascii te tekenen, hierbij zijn -, | en + de karakters voor de randen, en is het = teken een rand om de header en body te scheiden:

.. cssclass:: table-bordered table-hover

+---------------+---------+--------+
| Klantomgeving | Dragers | Orders |
+===============+=========+========+
| KLM           |   1.200 |     56 |
+---------------+---------+--------+
| Defensie      |   3.500 |    120 |
+---------------+---------+--------+

In dit voorbeeld zijn er ook 2 CSS classes aan toegevoegd, deze regel is optioneel. Het resultaat hiervan is:

Klantomgeving	Dragers	Orders
KLM	1.200	56
Defensie	3.500	120

Er is een maatwerk CSS class gedefinieerd die een tabel er uit laat zien als een Excel importtemplate:

.. cssclass:: table-bordered ecm-table-importsheet

+---------------+---------+--------+
| Klantomgeving | Dragers | Orders |
+===============+=========+========+
| KLM           |   1.200 |     56 |
+---------------+---------+--------+
| Defensie      |   3.500 |    120 |
+---------------+---------+--------+

Het resultaat hiervan is:

Klantomgeving	Dragers	Orders
KLM	1.200	56
Defensie	3.500	120

Als ASCII simpel

Er is ook een wat simpelere variant van bovenstaande ASCII waarbij je alleen de horizontale strepen gebruikt

.. cssclass:: table-bordered ecm-table-importsheet

============= ======= ======
Klantomgeving Dragers Orders
============= ======= ======
KLM             1.200     56
Defensie        3.500    120
============= ======= ======

Het resultaat hiervan is:

Klantomgeving	Dragers	Orders
KLM	1.200	56
Defensie	3.500	120

Als list-table

Of als de flow van tekst van belang is kan je gebruik maken van list-table

.. list-table:: config file
   :widths: 30 30 40
   :header-rows: 1

   * - Configuratie
     - Default
     - Uitleg
   * - MailServer
     - mail.leverancier.nl
     - Uw mailserver. Indien leeg dan worden er geen emails verstuurd. Hier kan nu dus een hele lange tekst staan die dan over meerdere regels loopt.
   * - MailFrom
     - ecmanageupload@leverancier.nl
     - Het from emailadres.

Het resultaat hiervan is:

config file

Configuratie	Default	Uitleg
MailServer	mail.leverancier.nl	Uw mailserver. Indien leeg dan worden er geen emails verstuurd. Hier kan nu dus een hele lange tekst staan die dan over meerdere regels loopt.
MailFrom	ecmanageupload@leverancier.nl	Het from emailadres.

Als csv-table

Of een csv-table

.. cssclass:: table-bordered table-hover
.. csv-table::
   :header: "Configuratie", "Default", "Uitleg"
   :widths: 30 30 40

   "MailServer", "mail.leverancier.nl", "Uw mailserver. Indien leeg dan worden er geen emails verstuurd. Hier kan nu dus een hele lange tekst staan die dan over meerdere regels loopt."
   "MailFrom", "ecmanageupload@leverancier.nl", "Het from emailadres."

Het resultaat hiervan is:

Configuratie	Default	Uitleg
MailServer	mail.leverancier.nl	Uw mailserver. Indien leeg dan worden er geen emails verstuurd. Hier kan nu dus een hele lange tekst staan die dan over meerdere regels loopt.
MailFrom	ecmanageupload@leverancier.nl	Het from emailadres.

Lijsten

Opsomming

Door regelt voor te gaan met 1 van deze karakters: - + * kan je een eenvoudige bullit lijst maken:

- eerste bullit

  - sub bullit

- tweede bullet

- en de laatste

Heeft als resultaat:

• eerste bullit

  • sub bullit

• tweede bullet

• en de laatste

Let wel op: Tussen een lijst moet altijd opgevolgd worden door een lege regel omdat het anders geinterpreteerd wordt als horend bij de bullit er boven. Zo kan je in de tekst newlines gebruiken voor leesbaarheid zonder dat het de lijst beinvloedt. Het is daarom wel zo mooi om tussen elke bullit een lege regel te doen, dan ziet dit er ook consistent uit als tekst.

Je kan lijsten ook nummers geven om deze expliciet te nummeren:

1. eerst bullet met expliciet 1 als cijfer

2. tweede bullet met expliciet 2 als cijfer

4. derde bullet met expliciet 4 als cijfer

#. vierde bullet met autonummering d.m.v. een hekje

Heeft als resultaat:

1. eerst bullet met expliciet 1 als cijfer

2. tweede bullet met expliciet 2 als cijfer

4. derde bullet met expliciet 4 als cijfer

5. vierde bullet met autonummering d.m.v. een hekje

Let op: omdat 2 en 4 niet opvolgend zijn, wordt het een nieuwe lijst en komt er witruimte tussen.

Je kan ook romeinse cijfers gebruiken:

I. Bullet 1

#. Bullet 2

#. Etc...

Heeft als resultaat:

1. Bullet 1

2. Bullet 2

3. Etc…

En het alfabet:

a. Bullet 1

#. Bullet 2

#. Etc...

Heeft als resultaat:

1. Bullet 1

2. Bullet 2

3. Etc…

Voor deze laatste 2 kan je kiezen voor zowel upper- als lowercase.

Definitie

Een manier om definities mooi weer te geven is met definitielijsten. Deze maak je door De het woord (of de zin) op de 1e regel te zetten, en de definitie hiervan op de volgende regel met een indentatie van 2 spaties. Je kan meerdere definities onder elkaar zetten gescheiden met een lege regel:

<Bedrijfscode>
  Acroniem (“acro”) als unieke identificatie klant.

<Naam>
  Naam van het bedrijf.

<Referentiecode>
  Optionele codering voor de klant.

Heeft als resultaat:

<Bedrijfscode>

Acroniem (“acro”) als unieke identificatie klant.

<Naam>

Naam van het bedrijf.

<Referentiecode>

Optionele codering voor de klant.

Code blokken

Er is een code-block definitie die je met een taal zoal gedefinieerd in the Python lexers kan opvolgen om een stuk code te tonen.

.. code-block:: plpgsql

   BEGIN
      -- Call the function
      :result := POM_EXPORT2.GetOrderXml(pnorderid => :pnorderid,
                                         pslanguage => :pslanguage);
   END;

Heeft als resultaat:

BEGIN
   -- Call the function
   :result := POM_EXPORT2.GetOrderXml(pnorderid => :pnorderid,
                                      pslanguage => :pslanguage);
END;

Je kan ook regelnummers aanzetten, en zelfs regelnummers highlighten.

.. code-block:: C#
   :linenos:
   :emphasize-lines: 1,14

   begin
      -- Call the function
      :result := pom_export2.getorderxml(pnorderid => :pnorderid,
                                         pslanguage => :pslanguage);
   end;

   public static void Main(string[] args)
   {
   }

   public WatchDirForFiles(string psDirectoryIn)
   {
      mbRunning = false;
      mbPause = false;
      log.Info("Start watching directory: " + psDirectoryIn);
      msDirectory = psDirectoryIn;

      ThreadStart loThreadDelegate = new ThreadStart(DoRun);
      moNewThread = new Thread(loThreadDelegate);
      moNewThread.Start();
   }

Het resultaat hiervan is:

begin
   -- Call the function
   :result := pom_export2.getorderxml(pnorderid => :pnorderid,
                                      pslanguage => :pslanguage);
end;

public static void Main(string[] args)
{
}

public WatchDirForFiles(string psDirectoryIn)
{
   mbRunning = false;
   mbPause = false;
   log.Info("Start watching directory: " + psDirectoryIn);
   msDirectory = psDirectoryIn;

   ThreadStart loThreadDelegate = new ThreadStart(DoRun);
   moNewThread = new Thread(loThreadDelegate);
   moNewThread.Start();
}

Plaatjes

Verwijzen naar plaatjes is zo simpel als zorgen dat het plaatje in de map staat (in dit voorbeeld de “media” submap in de map van de pagina zelf) en er naar te verwijzen met de image directive:

.. image:: media/Ecmanage_logo.png

Het resultaat hiervan is:

Speciale indicaties

Sphinx heeft admonitions, dit zijn de alerts zoals je ze verwacht, alleen is de opmaak hiervan extreem beperkt. Er zijn 10 varianten, maar die hebben maar 2 verschillende stijlen: rood of geel. Het verschil is de automatische titel.

Ook is er een generieke “admonition” die je kan gebruiken. Hiervan kan je zelf de titel invullen en met de class-parameter instellen welke css-class die moet hebben. Ik heb de 4 bootstrap classes gemaakt: danger, warning, info en success. Hieronder het resultaat:

Notitie

This is a note.

Waarschuwing

This is a warning.

Gevaar

This is danger-ous.

Voorbeeld generiek

dit is een alert met eigen titel en body