Skip to content

FAQ.md

Latest commit

 

History

History
543 lines (419 loc) · 30.9 KB

FAQ.md

File metadata and controls

543 lines (419 loc) · 30.9 KB
Raw

Frequently asked questions

The contributing guide outlines the basic steps of starting contributing to Docs CSC through pull requests. This page highlights in more detail common questions and pitfalls you may encounter during the process.

How to include my new page in the navigation sidebar?

Tip

The following is achieved by using two ProperDocs plugins. For more information/documentation, see

If you add a new page that you want to appear in the left-hand-side navigation panel, you need to edit the appropriate NAV.md file for the section you want your page to appear in. For example, the root NAV.md file, docs/NAV.md, defines the top-level sections as a list of Markdown links:

- [Accounts](accounts/)
- [Computing](computing/)
- [Cloud services](cloud/)
- [Data](data/)
- [Sensitive data](data/sensitive-data/)
- [Applications](apps/index.md)
    - [By discipline](apps/by_discipline.md)
    - [By availability](apps/by_availability.md)
    - [By license](apps/by_license.md)
- [FAQ](support/faq/index.md)
- [Tutorials](support/tutorials/index.md)
- [Training material](support/training-material/index.md)
- [Contact](support/contact.md)
- [What's new](support/whats-new.md)

Important

Four spaces are used for indentation.

The links to Markdown files appear as simple navigation items pointing to the page defined in that file. List items with nested lists under them define navigation sections, i.e. dropdown menus. Links where the target ends in a / are sections defined in another NAV.md file found in the target directory.

In the root NAV.md above, all of the sections are links, meaning the dropdown itself appears as a link leading to the index page for that section. When the target is a section defined in another NAV.md file, the index page for the section must be a file named index.md in the target directory. If the section is defined as a nested list, the file can be named freely.

- [Section with index page](path/to/the/page.md)
    - [Page under the section](path/to/another/page.md)

A navigation section without an index page can be defined as just a text item:

- Section without index page
    - [A page](path/to/some/page.md)

Warning

If you intend to make substantial changes to the navigation menu, please communicate this for example in the RC-channel #docs.csc.fi and/or #research.csc.fi as big changes may break some links used elsewhere.

How to add an image?

  • Add the image you want to include to the /docs/img/ directory.
    • If the image is really large, publish it in Allas in the docs-files bucket: a-publish my-image.png -b docs-files (write access with project 2001659)
  • Include the image in your page using the markdown syntax ![This is alt-text for screen readers](/path/to/docs/img/my-image.png 'This is mouse-over text')
  • Note the importance of alt-text and mouse-over (title) text! These are required to make the content accessible for all.
  • Alt-txt should not be too long (8+ words). If the alt-text cannot explain the information contained in the image, mention that the text below contains it.
  • You can use the same text in alt-text and mouse-over text
  • Images should be of high contrast and large enough font within them.

How to embed an external video?

  • You need to use the <iframe> HTML element, for example, <iframe width="560" height="315" frameborder="0" srcdoc="https://www.youtube.com/embed/PrgMFna3DKw" title="Adding and removing project members" allow="autoplay; encrypted-media" allowfullscreen></iframe>
  • Note, a www.youtube.com/embed/... style URL is required to appropriately embed the video, the normal URL will not work. You can right-click the video in YouTube to copy the normal URL, then just add /embed/. It's also possible to right-click the video to copy the embed code directly, but it needs to be edited a bit before it can be used, see below.
    • Remove any remaining search parameters present in the URL. In the example above, if the embed URL was formed by editing https://www.youtube.com/watch?v=PrgMFna3DKw, the first parameter would be the video ID as the key=value pair v=PrgMFna3DKw and prefixed with a "?". Any remaining search parameters would be prefixed with a "&" and should be removed. For example https://www.youtube.com/watch?v=PrgMFna3DKw&si=a-nasty-looking-tracking-identifier would need to be trimmed down to https://www.youtube.com/watch?v=PrgMFna3DKw before replacing watch?v= with embed/.
    • Edit width and height to match the example above.
    • Use the title to describe the content of the video.
    • Use of srcdoc is also required instead of plain src to avoid cookies if consent has not been granted.

How to embed a diagram from draw.io?

Diagrams from draw.io can be embedded as iframes by selecting File -> Embed -> IFrame.... As with videos, the iframe src attribute needs to be renamed to srcdoc, but no further changes are necessary. An example can be found in the Markdown source of the Reference card.

How to add links?

Links are added using the markdown syntax [This is my link text](link url or path). Whether to use a URL or path depends on if your link is internal, i.e. it points to another page within Docs CSC, or external. For example:

  • Link pointing to file in same directory: [Gromacs documentation](gromacs.md)
  • Link pointing to a certain section (anchor) in a page: [Gromacs usage](gromacs.md#usage)
  • Link pointing to a file in another directory: [Contact Service Desk](../support/contact.md), where the double dot ../ syntax means going up one level in the directory tree relative to the current directory. Then the path is followed to support and the contact page contact.md.
  • An absolute link to a file relative to the docs directory: [Contact Service Desk](/support/contact.md) (These do not work when, e.g., browsing the source files through the GitHub web interface).
  • For internal links you need to include the file extension .md in the target
  • Don't make internal links using a URL, https://docs.csc.fi/... or https://csc-guide-preview.rahtiapp.fi/.... Use URLs only in links pointing to an external target.
  • Always add a descriptive link text to make the content accessible. Plain URLs without link text are not acceptable! Screen readers will read it as h-t-t-p-s-colon-slash-slash...
    • [Read more here](gromacs.md#usage) is not accessible. [Read more about Gromacs usage](gromacs.md#usage) is better.
    • If, for some rare reason, writing a descriptive link text is not possible, you can use html and aria-label: <a href="https://code.visualstudio.com" aria-label="This is readable by screen readers">Visual Studio Code</a>. This label is read by the screen readers but is not visible to others.
  • For external links, make sure to include a target attribute with the value "_blank" to open them in a new tab: [example](https://example.com){ target="_blank" }

Common issues:

  • Incorrect number of double dots, i.e. going up too many or too few parent directories: [Service Desk](../../support/contact.md) vs. [Service Desk](../support/contact.md).
  • Including / between page and anchor
    • Correct: [Gromacs usage](gromacs.md#usage)
    • Incorrect: [Gromacs usage](gromacs.md/#usage)

My PR did not pass the tests, what to do?

Tests are run to check, for example, that your pull request complies with the CSC Docs style guide and that there are no broken links. If any such errors are found in your commits, the tests will not pass and you need to figure out what went wrong:

  1. Find out which tests did not pass under the notification Some checks were not successful in the Review-dialogue (marked with a red x and text Failing after X - Build Failed).

  2. To the right of the failed test, click Details, which opens the Checks tab.

  3. Under the Build Failed section, click the link at The build failed to open the Travis CI page with logged details on the build.

  4. Scan through the Job log for any text marked in red. These are errors that the test found, and the reason for them is written before the red text.

  5. An example error is shown below. Here, Travis is performing a test build of the site in "strict mode" to see if ProperDocs reports any warnings. Look for lines starting with WARNING - :

    INFO    -  whats_new-hook: What's new entries read from 'support/wn/data-new.md'.
INFO    -  whats_new-hook: What's new entries read from 'support/wn/apps-new.md'.
INFO    -  whats_new-hook: What's new entries read from 'support/wn/training-new.md'.
INFO    -  whats_new-hook: What's new entries read from 'support/wn/comp-new.md'.
INFO    -  whats_new-hook: What's new entries read from 'support/wn/cloud-new.md'.
INFO    -  glossary-hook: Glossary entries read from 'includes/snippets/glossaries/hpc.md'.
INFO    -  glossary-hook: Glossary entries read from 'includes/snippets/glossaries/cloud.md'.
INFO    -  testing-hook: test build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/joonaso/Worktrees/csc-user-guide.nav-md/site
WARNING -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
            - support/faq/why-is-my-pr-failing-the-tests.md
INFO    -  whats_new-hook: Appending What's new entries to 'index.md'.
INFO    -  glossary-hook: Writing glossary to 'support/glossary.md'.
INFO    -  whats_new-hook: Appending What's new entries to 'support/whats-new.md'.
WARNING -  Doc file 'support/faq/why-is-my-pr-failing-the-tests.md' contains a link '/dev/null', but the target is not found among documentation files.
INFO    -  testing-hook: DocsTests.no_fixmes_are_present_in_documentation_sources: [Passed: 0, Failed: 1]
WARNING -  testing-hook: FIXME found on support/faq/why-is-my-pr-failing-the-tests.md line(s) 42!
INFO    -  testing-hook: None of the documentation source files should include the word 'FIXME'.
INFO    -  testing-hook: DocsTests.app_page_contains_license_heading: [Passed: 220, Failed: 0]
INFO    -  testing-hook: DocsTests.doc_page_has_no_internal_links_to_production_domain: [Passed: 758, Failed: 1]
WARNING -  testing-hook: The hyperlink 'this' on page support/faq/why-is-my-pr-failing-the-tests.md points to 'docs.csc.fi'!
INFO    -  testing-hook: No internal links should point to the site domain.

Aborted with 4 warnings in strict mode!
The command "bash tests/checkbuild.bash" exited with 1.

  6. Fix the errors, commit and push the revised files to the same branch and the tests should now pass.

How can I preview my edits?

You can preview how the Docs CSC page would look like with your changes included in two main ways:

Using the preview feature for active branches hosted on Rahti

Locally using the ProperDocs tool

This user guide uses ProperDocs to generate documentation pages. ProperDocs comes with it's own preview server for a quick local preview of your edits. You can install the requirements for running Docs CSC locally (all of the following commands are to be run while in the root directory of the cloned repository) with Pip or Conda (recommended).

Venv

If you have a suitable Python version (i.e. equal or greater to the one defined in the latest Conda environment file symlinked here; see Conda below, if not) installed, you can create a new virtual environment with

python -m venv docs-env

activate it with

source docs-env/bin/activate

Note

On Windows, use docs-env\Scripts\activate.ps1 with PowerShell, or docs-env\Scripts\activate.bat with cmd.

and upgrade Pip with

pip install --upgrade pip

Then, to install the requirements for Docs CSC, run the command

pip install -r requirements.txt

Conda

Detailed instructions for installing Conda on Windows are found here, but the gist of it, regardless of the operating system used, is to install Miniconda, use it to create a virtual environment to install the requirements in. So, with Miniconda installed, an environment to run ProperDocs in can be created by running the command

conda env create -f development/conda-docs-base-latest.yaml

Add a --force flag if you already have a Conda environment named docs-env (you got CondaValueError: prefix already exists: [...]) and want to overwrite it. The environment is now ready for installing the requirements.

conda run -n docs-env pip install -r requirements.txt

If you want to reinstall the dependencies, add a --force-reinstall flag to the Pip command.

Activate the new environment with

conda activate docs-env

Preview server

You can start a preview web server with the command

properdocs serve

This will start a web server on your computer listening on port 8000. Go to the url http://127.0.0.1:8000/ or http://localhost:8000/ with your browser to get a preview of the documentation.

  • to speed up the reloading of a page you've changed, you can start the ProperDocs server with the --dirty flag. (Mind the warning about "a 'dirty' build being performed" that will "likely lead to inaccurate navigation and other links [...]".):
properdocs serve --dirty

Tests

You can also run the tests locally with

PROPERDOCS_ENV=test bash tests/run_tests.sh

The tests depend on the Conda environment, so remember to activate it before running them, or use conda run -n docs-env PROPERDOCS_ENV=test bash tests/run_tests.sh.

How and who should I ask to review my PR?

  1. Ask someone (one or two persons) who knows the content of the work you have committed to review your pull request. This is done in your pull request view using the right-hand-side panel, under Reviewers. The panel will suggest a few names for you based on, for example, who has edited the same pages recently. To view more reviewer options, click the cogwheel in the upper right corner of the Reviewers panel. If you're still unsure who to pick, you can always drop a message in the Rocket Chat channel #docs.csc.fi. Always request someone to review your PR, otherwise there's a high chance that it will just linger around.
  2. To help the reviewer to get started with going through your PR, you should leave a comment in the PR with a link to the preview page https://csc-guide-preview.rahtiapp.fi/origin/your-branch/path/to/page/ with your additions/changes (edit /your-branch/path/to/page/ as needed). Any other comments are of course also helpful for the reviewer to understand what you have done.
  3. Once the reviewer has gone through your PR, they will request changes or approve the PR. Once approved, someone with merge permissions will merge your PR to the master branch. If the changes you have made are urgent, you can always ping the Rocket Chat channel #docs.csc.fi to expedite the merging of your PR.

I was asked to review a PR, what should I do?

  1. Read any comments left by the requestor. If you understand the content of the PR and have time, you're up for the task. Otherwise, communicate to the requestor that you're unable to review the PR so that they can request someone else.
  2. Ensure that all tests have passed. If the tests are failing, notify the requestor. See also above.
  3. Check which files have been modified under tab Files changed. The panel shows the diff, i.e. which lines have been deleted and which have been added. Focus on these changes, but also look that the content looks good and is correct overall. Are there typos, is the text clear and concise, is the content accessible (see Style Guide)?
  4. Go to the Rahti preview page of the branch and check that the formatting of the page looks good. If the requestor has not left the preview link as a comment, select the branch from list. The name of the branch can be seen in the PR under the title (e.g. username wants to merge N commits into master from name-of-branch). It's important that you view the page in the preview because the preview feature of GitHub does not show all formatting correctly, e.g. indentation of bullet-point lists. Check that links work. Note that absolute internal links will not work in the preview, but work on docs.csc.fi.
  5. If there are small errors, for example typos, you can correct these directly in the PR: In the Files changed tab go the file you want to correct, select Edit file (behind the three dots in the top right corner). Commit the corrections to the same branch so that they get added to the PR!
  6. If there are substantial revisions that should be made, click the green Review changes button in the top right corner and select Request changes. You can also leave general feedback without explicit approval. It's a good idea to suggest changes so that they appear as a diff in the conversation tab, see here.
  7. Once all corrections have been made, approve the changes (also behind the Review changes button). Someone with merge privileges will merge the PR into master.

When reviewing a PR, how to leave comments/suggest changes so that they appear as a diff in the conversation tab?

It's good practice to leave comments/suggest changes to a PR so that they appear as a diff in the conversation tab. To do this,

  1. In the Files changed tab, go to the line you want to edit and click the blue + sign.
  2. In the pop-up, write you're comment, or if you want to suggest changes, click the stacked +- icon in the top bar.
  3. Write between the tics (including the word "suggestion") what you want to appear in the page.
  4. If you want to remove a line, delete the content (leave the tics and the word suggestion)
  5. If you want to edit multiple lines, click and drag the + sign to select all lines.
  6. Once done, click Add single comment.

If you want to add changes suggested by a reviewer, go to the files changed tab, find the suggestions you want to add to your pull request and -if you have multiple suggestions to add - choose add suggestion to batch. Once you added all suggestions to the batch, you can find a commit suggestions button with the number of changes that will be committed under each added suggestion or in the top right of the files changed page. Once you click that, you can provide a commit message and commit all changes at once to your branch.

How do I add an entry to the "What's new" section

A good way to highlight a new update is to add an entry to the What's new -section. Follow these steps:

  1. Do not edit the index.md landing page or whats-new.md files. Instead go to docs/support/wn/ and edit the file which applies best for your update
    • apps-new.md = New installed software or updated version
    • comp-new.md = Updates to the computing environment, e.g. SLURM updates, new/deprecated libraries, web interface..
    • training-new.md = New/updated tutorials or training materials published
    • If these categories do not match your update, you can add a new file with similar structure as the above ones. It is also a good idea to consult #docs.csc.fi RC channel first.
  2. At the top of the file, add a new level 2 heading (##) for your update including a descriptive title followed by the current date.
    • For example, ## SoftwareX v1.2.3 installed on Puhti, 31.3.2022
  3. Under this heading, describe the update with a few sentences. Include links to appropriate pages elsewhere in docs, as well as external links to e.g. release notes/changelog if applicable. If you need to add an image, you can put it in docs/img/whats-new/.
  4. Commit your changes and when the PR gets merged a script will automatically add your updates to the docs landing page.

Which Markdown features/extensions are available?

Have a look at the reference card.

How do I add definitions to the glossary / display definitions as tooltips?

There are .md files that contain acronym-definition pairs in includes/snippets/glossaries/. The pairs are in the format *[Acronym]: Definition. The Acronym part is case-sensitive, so if you'd add the definition *[PCIe]: Peripheral Component Interconnect express, instances of PCIE in the text would not get the tooltip (in this case the definition is correct, so text would have to be corrected). If the acronym you wish to define already exists, please use the following format to add an additional definition: *[DFT]: 1. Discrete Fourier Transform, 2. Density Functional Theory. New acronym-definition pairs may be added to an existing file, or a new file may be created within the same directory. The new file must then be introduced in properdocs.yml. An example is found in the reference card.

The glossary is also viewable as a page at docs.csc.fi/glossary.

How do I use the announcement bar?

The announcement bar below the header is controlled by editing the extra.announcement mapping in mkdocs.yml:

  • announcement
    • icon pick an icon here
      • name replace the first - with /; prefer 'material' icons
      • mirror mirror the right-hand side icon (true or false)
    • color_scheme pick a color here (null for the yellow note color)
    • content the content of the announcement, in HTML
    • visible show/hide the announcement (true or false)

The href attribute for internal hyperlinks must start with {{ base_url }}. Note that this is not a Markdown link.

extra:
  # ...
  announcement:
    icon:
      name: material/beaker-outline
      mirror: true
    color_scheme: error
    content: |-
      <p>Announcement content in HTML. <a href="{{ base_url }}/path/to/page/">Click here for more information</a>.</p>
    visible: true
  # ...

How do I add a new "Applications" page?

To include a new software page on the "Applications" index pages (apps/index.md, apps/by_discipline, apps/by_availability.md, apps/by_license.md), you must add a YAML front matter at the beginning of the file (before the page title) with appropriate metadata. The frontmatter should look like this:

---
tags:
  - <license type>
catalog:
  name: <software name>
  description: <short description>
  license_type: <license type>
  disciplines:
    - <discipline a>
    - <discipline b>
    - ...
  available_on:
    - web_interfaces:
        - <system 1>
        - <system 2>
        - ...
    - <system 1>
    - <system 2>
    - <system 3>
    - ...
---

For example, the front matter of MATLAB is:

---
tags:
  - Academic
catalog:
  name: MATLAB
  description: High-level technical computing language
  license_type: Academic
  disciplines:
    - Mathematics and Statistics
  available_on:
    - web_interfaces:
        - LUMI
        - Puhti
    - LUMI
    - Puhti
---

A missing name causes even preview builds to stop immediately with an error:

ERROR   -  Error reading page 'apps/doom.md':
ERROR   -  Every application in the Software Catalog must have a name

Other missing values in the front matter will generate a warning:

WARNING -  catalog-hook: Doc file 'apps/doom.md' is for an application, but the YAML front matter does not ...

Warning

Warnings are not allowed in the test automation, so while the site can be built with warnings for a preview (local or Rahti), all of the fields must be defined for a branch to be merged into the master branch.

To include an app page without warnings for missing fields, the app may be marked as "unchecked". by defining a boolean-valued key unchecked: true inside catalog:.:

---
catalog:
  name: A name is still required
  # ...
  unchecked: true
---

Important

Do not attempt to include apps on apps/index.md, apps/by_discipline, apps/by_availability.md, apps/by_license.md pages by hand, as the indices are populated automatically by a script using the front matter data when the website is built.

See also:

How do I add a license tag to an application page?

The license tag is added inside the YAML front matter. Temporarily, the license type should be placed as a single list item under tags: and as a string in license_type::

---
tags:
  - <license>
catalog:
  # ...
  license_type: <license>
  # ...
---

where <license> is one of the predefined license categories: Academic, Free, Non-commercial or Other; case sensitive, without the angle brackets.

The application will then be included under the appropriate license category on the Applications by license page automatically.

How do I tag an application as available under a web interface?

In the YAML front matter. The following would, for example, tag the application as available on Puhti, Mahti and Puhti web interface.

---
catalog:
  # ...
  available_on:
    - Puhti
    - Mahti
    - web_interfaces:
        - Puhti
  # ...
---

How do I add scientific disciplines to an application page?

Similarly to license and availability above. The disciplines are to be listed under disciplines::

---
catalog:
  # ...
  disciplines:
    - Biosciences
    - Chemistry
  # - ...
  # ...
---

The application will then be listed under each of those disciplines on the Applications by discipline page automatically.

See the 'catalog-hook' configuration file for a list of predefined disciplines.

What if there is no application page, but the application still needs to be listed on the index pages?

There is an appendix for including such applications. It resides in the 'catalog-hook' configuration file. The list appendix: contains entries such as

appendix:
  - name: "Chipster"
    description: "Easy-to-use analysis platform for RNA-seq, single cell RNA-seq and other NGS data"
    disciplines:
      - "Biosciences"
    doc: "https://chipster.csc.fi/"
  - name: "MaxQuant"
    description: "A proteomics software for processing of Mass-spectromtery data"
    disciplines:
      - "Biosciences"
    doc: "support/tutorials/MaxQuant-tutorial.md"
# - ...

where doc: can point either to an external page or a .md source file on Docs. For the other fields, see the instructions for application pages above. The fields name:, description:, disciplines: and doc: are all required and no other fields are allowed.

How do I add footnotes?

Usage of the footnotes feature is described here.

How do I improve search results?

You can boost a page to be on top of the results by adding the following lines at the top of the Markdown file:

---
search:
  boost: 2
---

# Document title
...

Start with low values.
More information here

How do I redirect incoming links

The STYLEGUIDE.md describes how to add redirection for a URL.