Git Product home page Git Product logo

poppy-docs's Introduction

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.

Where to start

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

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:

Fork the repository

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

Fork button

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.

Edit button

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

GitHub editor

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 [email protected]: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

PR

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.

poppy-docs's People

Contributors

antoinepringalle avatar bcopy avatar blackpowder avatar cjlux avatar dashdashzako avatar mademang avatar manon-cortial avatar matthieu-lapeyre avatar noerw avatar octavedelorme avatar paulecoffet avatar pierre-rouanet avatar show0k avatar tgll avatar tibo42 avatar titimoby avatar ymollard avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

poppy-docs's Issues

Inconsistent structure of the doc

The tree view of folders are not consistent in the folder tree structure, in the rended HTML and in the pdf which is very confusing....
html
pdf
folder_tree

Git repository is FAT

We did lot of bad commit of PDFs, large images, large GIF and so on, so the repository was above 460MB.

I used bfg to delete blob above 3MB which are not referenced in HEAD. The repo weighs now 200MB which is more acceptable but not ideal.
This command didn't break existing clone on your computer but caused lot of false new commits in GitHub hook.

I would like to add a symbolic link of all images in the french folder to the english one to avoid data duplication.

Move to mdbook

Gitbook is abandoned, moving to mdbook shouldn't be much work

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.