Service Documentation Guidelines

Summary

Here you can find basics about Markdown, instructions for installing MkDocs, Service Documentation environment in gitlab and examples of the relevant web servers defined in EOS, which seems to be a simple-enough option for static documentation sites.

This is a proposal about CERN/IT-CDA Documentation strategy, discussed with CDA section managers between 2018-08-22 and 2018-10-31. Conclusions reached thanks to our group discussions on Documentation https://twiki.cern.ch/CDAgroup/CDAPublicDoc#Autumn_2018 status.

Technical steps needed to write Service Pages in Markdown

1. About MkDocs: Very basic steps follow but a more complete document is available from https://gitlab.cern.ch/authoring/documentation/mkdocs . To download MkDocs from here. MkDocs is recommended due to the uncertain GitBook future, as an Open Source product. The advantage of having mkdocs locally is that you can check your edits via http://localhost:8000/ before you publish. If you use MkDocs all .md files should be under a directory called docs. Also, the list of contents of your site (shown on the left banner) and its colours should be entered in the file called mkdocs.yml. If a .md file exists but is linked from nowhere, http://localhost:8000/ will claim that the page doesn't exist. To install and "serve" your work:

   sudo pip install mkdocs
   sudo pip install mkdocs-material
   sudo pip install --upgrade mkdocs (if needed...)
   sudo pip install --upgrade mkdocs-materials (if needed...)
   mkdocs serve (go to  the local directory that contains the files of your site before you launch this command)
   

2. Use your preferred editor, e.g. Atom or Visual Studio Code.
3. Create a gitlab repository where the Service Pages of Your_Service will live. Here is a boilerplate setup https://gitlab.cern.ch/it-dep-cda/docs-boilerplate to Fork (see button on top banner) and rename (see how) to https://gitlab.cern.ch/docs-Your_Service . Example: https://gitlab.cern.ch/dimou/it-e-learning NB! As soon as you create your project, go to Settings->General->Advanced (Expand)->Remove fork relationship! Else, your updates will go to the original boilerplate!!
4. To deploy the gitlab repository with the Markdown (file.md) documentation in it, one needs to:
   • create a service account with access to some EOS folder (in the EOS workspace dir, like indico or in the EOS project dir, like elearning) which should host a corresponding web site, e.g. docs-Your_Service. For OpenShift to host the web server instructions here

Markdown basics to write pages:

--- Horizontal line OR two empty lines = New slide
## Header 2 (H1 is reserved for post titles) 
### Header 3 
#### Header 4 
A link to [Jekyll Now](http://github.com/barryclark/jekyll-now/). 
Video insert: <iframe width="576" height="360" frameborder="0" src="https://cds.cern.ch/video/2261867?showTitle=true" allowfullscreen></iframe> 
An image, located within /images; ![an image alt text](/images/image-filename.png "an image title") 
* A bulletted list 
- alternative syntax 1 
+ alternative syntax 2  
  - an indented list item
_italics_ - 
**bold** - 
`code()` 

https://en.support.wordpress.com/markdown-quick-reference/

https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Gitlab notes to publish pages:

The Indico Service example - end-user documentation:

• Service account: indico
• EOS directory: /eos/workspace/i/indico/sites/indico-user-docs.cern.ch
• Published files live in https://gitlab.cern.ch/indico/indico-user-docs-cern
• From the browser you see them under https://cern.ch/indico-user-docs/
  • You can see the identical contents of https://gitlab.cern.ch/indico/indico-user-docs-cern/blob/cern/docs/categories/creating.md (in gitlab) with https://cern.ch/indico-user-docs/categories/creating/ (the web view). The embedded images come from the https://gitlab.cern.ch/indico/indico-user-docs-cern/tree/cern/docs/assets dir.

To edit your pages locally:

1. Make a local folder to clone the site
2. Clone the published version from gitlab to this local folder (requires CERN login). To do this, type: git clone https://gitlab.cern.ch/docs-Your_Service.git. The SSH option is better so that you don't login every time... You have to enter your key in gitlab.
3. Open local folder docs-Your_Service with your preferred editor and enter content in individual files.md.

To publish in gitlab:

1. save (local in editor)
2. stage (local in project)
3. define new branch name from within your editor (branching is optional but recommeded, especially if there are several co-authors).
4. commit (with a msg)
5. push (branch name will be created at the gitlab destination project, if it doesn't exist)
6. review your changes via URI http://cern.ch/docs-Your_Service/review/<_yourbranchname_>/<_path-to-the-page-you-edited>. This is possible IF your .gitlab-ci.yml, the file that takes care of the site building and publishing rules, has this option enabled. See an example here or here.
7. create a merge request, if happy with the changes. To CHECK publishing activity, click on the gitlab pipelines (left banner CI/CD link). NB! You have to configure the project to merge into the master of your https://gitlab.cern.ch/docs-Your_Service.git and not the original boilerpoint from where you forked.

Restricting a sub-directory in Gitlab

Input by Iago Pardo & Thomas Baron:

• About the repository in Git, if the project is set as public, a sub-directory inside this project will always be public.

• About restricted web visibility (e.g. for https://cern.ch/it-e-learning/administration/ ):
  • go to the subdirectory `administration` in EOS (e.g. accessible by CernBox -> your Projects -> )and create a .htaccess file which will contain the following:

### Control access to the site adding the following file in EOS .htaccess

#Header unset ETag
Header set Cache-Control "max-age=0, no-cache, no-store, must-revalidate"
Header set Pragma "no-cache"
Header set Expires "Wed, 11 Jan 1984 05:00:00 GMT"

SSLRequireSSL # The modules only work using HTTPS
AuthType shibboleth
ShibRequireSession On
ShibRequireAll On
ShibExportAssertion Off

Require valid-user
Require ADFS_GROUP "<your admin e-group>"

Adding this file into the subdirectory will only be accessible for the members of the e-group.

Example:

https://gitlab.cern.ch/dimou/it-e-learning results into https://cern.ch/it-e-learning which should be public

https://gitlab.cern.ch/dimou/it-e-learning/tree/master/docs/administration can be seen by authorised Gitlab users in this project but the resulting http://cern.ch/it-e-learning/administration/ should only be seen by the it-dep-cda e-group.

-- MariaDimou - 2018-05-02