Dolittle Documentation

Get started

All of Dolittles documentation is open-source and hosted on GitHub.

Quick edits online

You can edit and create pull request for documentation online straight from dolittle.io.

  1. Click the pencil icon next to the document title at the top of the page you want to edit. This takes you to the pages GitHub source file.
  2. Make your changes in the web editor.
  3. Once you have made your changes click Propose file change at the end of the page.
  4. On the next page click Create pull request and add a title for the pull request.

Read the style guide for more information how to style your documentation.

Editing dolittle.io locally

You can run your own copy of dolittle.io on your local machine. This way you get a feeling for how it will look like and verify that links, images and diagrams are correct.

Prerequisites

Run the documentation locally

Run the dolittle-documentation-server script from withing your local Dolittle git repository. The script will automatically mount the correct folders inside the docker image and start a Hugo webserver that will watch for changes.

It doesn’t matter which subfolder you’re in as long as your in the git repository.

cd ~/Dolittle/Documentation
dolittle-documentation-server

The output looks like this:

Mounting folder /home/joel/Dolittle/Documentation to /Documentation

                   | EN
+------------------+-----+
  Pages            | 383
  Paginator pages  |   0
  Non-page files   |  53
  Static files     |  26
  Processed images |   0
  Aliases          | 107
  Sitemaps         |   1
  Cleaned          |   0

Built in 1052 ms
Watching for changes in /Documentation/{Documentation,Source}
Watching for config changes in /Documentation/Source/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:1313/ (bind address 0.0.0.0)
Press Ctrl+C to stop

In your browser navigate to localhost:1313 to see the documentation, the page will live reload your changes. Any errors will be displayed on the docker output.

You are now ready to write documentation in your local repository. Read the overview and style guide for more information on how you should be writing documentation.

Add a new repository to the main Documentation repository

This guide teaches you how to add a new repository to the Dolittle documentation structure and how to keep dolittle.io synchronized with the changes.

Start by cloning the Documentation repository and its submodules:

$ git clone --recursive https://github.com/dolittle/documentation

If you’ve already cloned it, you can get the submodules by doing the following:

$ git submodule update --init --recursive

1. Create documentation for the new repository

At the root of the working repository, create a Documentation folder with at least a matching _index.md and other markdown files if needed. Read our guide on structure for more information.

2. Adding the working repository as a submodule

In the Documentation repository, navigate to the Source/repositories/ folder and then into the corresponding organisation folder (e.g. fundamentals, runtime, interaction etc). If the organisation is “dolittle” then use the repository name eg. learning.

Pull your working repository here as a submodule:

$ git submodule add <repository_url> <repository_name>
Organisation/repository name inside Source/repositories has to be in lower case.

Example from dolittle/Documentation root:

cd Source/repositories
$ git submodule add https://github.com/dolittle-fundamentals/dotnet.fundamentals.git dotnet.fundamentals

3. Linking submodules to content

The system relies on all documentation content sitting in the Source/content folder. This includes markdown files, images and other resources you link to your documentation.

The content folder contains the parent folders, with a matching _index.md and the contents of the Documentation folder from the repository directly in this.

This is done by creating a symbolic link to the repositories Documentation folder.

<Documentation root>
└── Source
    └── content
        └── fundamentals
        └── runtimes
        └── ...

Open a shell and navigate to the correct sub-folder in the content folder and then in the corresponding organisation folder.

Unix:

$ ln -s ../../repositories/<organisation-folder>/<repository>/Documentation <folder-name>

Windows:

c:> mklink /d <folder-name> ..\..\repositories\<organisation-folder>\<repository>\Documentation

Example:

Unix:

$ ln -s ../../repositories/runtime/Runtime/Documentation runtime

Windows:

c:> mklink /d runtime c:\Projects\Dolittle\Documentation\Source\repositories\runtime\Runtime\Documentation

Chances are you are contributing to the code of the repository and you can therefor leave it in place and maintain code and documentation side-by-side.

All folder names given in this process will act as URL segments, be very carefull to change these after they have been deployed.

4. Keep main Documentation syncronized with the working repository

An Azure pipeline keeps the main Documentation repository up-to-date automatically when modification is made in a repository.

To use that from a working repository, a simple pipeline is needed to call the Documentation update.

azure-pipeline.yml :

trigger:
    - master

resources:
    repositories:
        - repository: templates
          type: github
          name: dolittle-tools/AzureDevOps
          endpoint: dolittle-tools

jobs:
    - template: Source/Documentation/documentation.yml@templates

You can use another template if needed but Source/Documentation/documentation.yml has to be triggered.

Writing

All documentation is written in markdown following the GitHub flavor.

Markdown can be written using simple text editors (Pico, Nano, Notepad), but more thorough editors like Visual Studio Code or Sublime Text are highly recommended. VSCode also has a markdown preview feature.

Read the writing guiden and style guide for more information.