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
- 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)
- Use your preferred editor, e.g. Atom
or Visual Studio Code
.
- 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!!
- 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; 
* A bulletted list
- alternative syntax 1
+ alternative syntax 2
- an indented list item
_italics_ -
**bold** -
`code()`
More on Markdown in
https://en.support.wordpress.com/markdown-quick-reference/
and
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
Gitlab notes to publish pages:
The Indico Service example - end-user documentation:
To
edit your pages locally:
- Make a local folder to clone the site
- 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.
- Open local folder docs-Your_Service with your preferred editor and enter content in individual files.md.
To
publish in gitlab:
- save (local in editor)
- stage (local in project)
- define new branch name from within your editor (branching is optional but recommeded, especially if there are several co-authors).
- commit (with a msg)
- push (branch name will be created at the gitlab destination project, if it doesn't exist)
- 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
.
- 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.
### 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