marutpong/poppy-docs

Documentation of the whole poppy platform

Poppy documentation

This is the source code repository for the documentation of the Poppy Project. The documentation is visible on docs.poppy-project.org so if you want to read it, please go there. If you want to contribute please do go further with this file.

Documentation is also available to download as PDF.

How to contribute

The Poppy Documentation under the Creative Commons Attribution-ShareAlike 4.0 license. Everyone is free to edit, correct and share the documentation.

Where to start

There are some of places where you can find something to contribute to:

• The issues in the issue tracker.
• The TODO links or comments in the markdown files.
• The broken links in the travis-ci logs (the ci build will fail if there are broken links) .

Editing basics

The source code of the documentation is hosted on GitHub. The GitHub Fork & Pull workflow is used to accept and review changes.

The documentation is written in the Markdown markup language and uses the GitBook service for publishing the rendered website. See more information about how GitBook works.

You can find discussions about the contents of the documentation on the issue tracker.

Getting started and prerequisites

Contributing to the documentation requires the following:

• A GitHub account.
• In the case of complex edits familiarity with Git command line basics or familiarity with an application (Windows, Mac) to push your edits made on your computer to GitHub.

Fork the repository

First fork the poppy-project/poppy-docs repository to your personal GitHub account:

Editing chapter content

Simple changes

For simple changes like typo corrections you can use the GitHub online editor:

1. Open your local fork page on GitHub,
2. Go to README.md file in any chapter,
3. Press the Edit icon (pen).

and you can edit the chapter directly on github.com.

Markdown syntax is used to edit the individual pages of the documentation.

Click on "Commit changes" to save your changes and create a pull request as explained below.

New content and complex changes

To add new chapters, write longer snippets of text or add images, you first need to fetch a copy of the documentation on your local computer.

Either use the GitHub app for your operating system (mentioned above) or git command line to get the repository locally. The repository address is located on your own GitHub repository fork front page:

git clone git@github.com:yourgithubusername/poppy-docs.git

Then, create a branch for your new changes to sit in. Naming the branch in relation to the changes you will make can help.

git checkout -b contributing

Download the GitBook Editor application to your computer.

Then you can open the documentation in GitBook Editor (File > Open book).

Make any changes in the documentation using GitBook and then save changes (Book > Save all).

If you don't want to download the GitBook Editor app you can also go to the GitBook website, sign up for free with your GitHub account, then work directly in your browser.

Making a pull request

After you are done editing, you have to create a pull request on GitHub. PoppyGirls will get notified about the pull request, review your changes, suggest any corrections if needed and then pull your changes to the master version.

In your own repository on GitHub press do Compare & pull request

Fill in the information why this change is being made. The reviewer can see the details of the actual change, so you don't need repeat the content of the change.

Then press Create pull request.

GitHub emails will notify you for the follow up process.

Building the documentation (advanced users)

If you want to build the HTML version on your computer, without installing the desktop application of the GitBook Editor, you can also build the book with a command line tool.

You have to install npm and calibre (the way depends on your OS).

git clone https://github.com/poppy-project/poppy-docs.git
cd poppy-docs/

npm install gitbook-cli -g
gitbook install
gitbook build ./
gitbook pdf ./

Further information and help

GitHub has an excellent documentation. Check it out if you need help! For further questions feel free to post thread in the Poppy Project forum.