Skip to content

SetupAnEditingEnvr

Trevor Y. H. Ho edited this page May 8, 2021 · 1 revision

Setting up a Docker environment for wiki editing

A Docker container for preview while editing this wiki

It is possible to set up a live server while editing this wiki. The changes can be immediately visualized.

This page provides the step-by-step instructions on how to do so, assuming that an editor has prior experience with Git, GitHub, Docker and Python.

First-time software installation and preparations

  1. Register for a GitHub account.

  2. Go to the repository page github.com/idechq/idec-wiki.
    Fork this repository under your own account.

  3. Install Docker Desktop.

  4. Install GitHub Desktop.

  5. Go to GitHub Desktop, select "File" -> "Options".

    In the "Options" window, under "GitHub.com", click on "Sign In".

    Follow the instructions and sign into your registered account.

  6. Go to the forked repository, which should now be https://github.com/{your username}/idec-wiki,
    click on the green button for downloading the code, and underneath select "Open with GitHub Desktop".

    This process will "clone" the repository to your local computer.

The steps above only need to be executed once.

Set up a Docker container and editing

  1. Open a command line terminal.
    (For Windows users, open a PowerShell terminal).

  2. In the terminal, navigate into the idec-wiki folder where this repository is cloned, e.g..:
    cd.. Documents/GitHub/idec-wiki

  3. Run the command ls, you should see a list of files and a folder, including:

    • the docs folder where .md files are stored, the wiki contents are in the .md files
    • Dockerfile, which is required to set up a Docker container.
    • mkdocs.yml, a configuration file that should not be touched unless the navigation menu is to be updated.
  4. Create a Docker Image by running the following command in the terminal:
    docker build -t squidfunk/mkdocs-material .

  5. Run the following command in the terminal to set up a local live server:
    docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
    You should see a message saying that changes are being detected:

    If an error message shows up here, please contact us at support@idechq.org

  6. Open your browser of choice (e.g. Chrome, Safari, Firefox, etc.),
    connect to the live server by typing the following in the address bar and hit Return:
    localhost:8000
    You should now see the wiki site being rendered locally.

  7. Open a text editor, make any changes to the .md files inside the folder docs and save them.
    All changes saved will be rendered in real time in the browser.

  8. Preview the changes in your browser, refresh the page if necessary.

  9. When you are done editing and no longer need your browser,
    go back to the terminal, hit Ctrl + C on your keyboard to exit the live server.

    Once you have done so, refreshing the page should give you a 404 error.

Incorporating your changes into the original wiki repository

  1. Open GitHub Desktop. After you have saved your changes, GitHub Desktop should have detected them.

  2. Once you are certain that the changes are finalized, "commit" the changes.

    It is always a good habit to leave a commit message that concisely summarizes what your changes are.
    For example, "Add references for Genome Evolution page" is better than "Update Genome Evolution"
    Read more on how to write better commit messages.

  3. Once a commit is done, the commit would become part of the "history" under verison control.
    At this point, this commit is appended to your local repository on your computer, but not yet on your remote and forked repository hosted on GitHub at https://www.github.com/{your username}/idec-wiki. To proceed, "push" the commit(s).

  4. Open a browser, travel to your forked repository on GitHub, the address should look be:
    https://www.github.com/{your username}/idec-wiki
    At this point, all changes you made are yours, i.e. they are not yet incorporated into our HQ maintained repository.
    Hence, the changes are not yet reflected on wiki.idec.io.

    Note the following:

    • Your lastest commit message should be displayed on top of the repository contents.
    • GitHub should compare your commits against ours and display a message saying:

    This branch is { a number } commits ahead of idechq:main.

  5. Click on the Contribute link, then click on Open pull request.

  6. This will lead you to a new page, which shows all differences between your edits and the original files.
    Click on the Create pull request button.

  7. Provide a subject and a message describing what the changes are, and click the Create pull request.

  8. Our wiki team will then review your edits and incorporate them if they are deemed ok.
    The more information you provide, the easier it is for us to review your changes.
    In cases where there are issues, our wiki team will reply to you in the thread and discuss the changes with you.

Subsequent editing

Through the course of editing, it is possible that someone else from our Resources team updates the repository and make edits to the contents. Therefore, before you start editing again, it is important to update your own local and remote repository and incorporate any new changes. To do so, following the steps below:

  1. Open GitHub Desktop. Click on the "Current branch main" icon,
    then, click on "Choose a branch to merge into main"

  2. Select the branch upstream/main.
    If there are any new commits on the HQ maintained repository, a merge message will appear saying:
    This will merge { a number } commit(s) from upstream/main into main
    If this message appears with a tick, click on the blue buttom "Merge upstream/main into main".

  3. Once a merge is completed, click on the history tab.
    The commit from the HQ maintained repository will now be added to your local history.
    To update the history on your remote repository, perform a "push".

  4. You can return to set up a docker container and proceed with your editing.