Contributing to Documentation
You will need a Github login to make and submit changes to this guide.
This guide is written in markdown wiki syntax and stored in the Github dronecore/docs repo. The book is hosted on Gitbook.com and is automatically rebuilt whenever the master branch of the repo is updated. You can also rebuild it locally using the Gitbook toolchain.
The API Reference section is compiled from source code into markdown using a separate toolchain and then copied into Github. Updates to the reference should be made in the source code repository (see API Reference below for more information).
The guide is licensed under CC BY 4.0 - if you make any changes then they will be made available under the same license.
Making a Quick Fix
Simple fixes to an existing page can be made directly on Github:
Click the Edit button in the top toolbar to open the page
Make required changes in the editor section near the top of the page.
At the bottom of the page, add a comment and select the second radio button to create a new branch.
Follow the on-screen instructions to create a pull request with your change.
Raising an Issue
To raise an issue against the documentation:
- Open the page with problem content.
Click the Bug button in the top toolbar.
This will open a bug in Github, seeded with the URL/name for the current page.
- Enter enough information for someone to understand the problem, and ideally to fix it.
Making a Big Change
If you want to make more significant changes or additions to the documentation you will need to set up Git and the gitbook toolchain (this allows you to render the documentation and check that links work).
For setup information see: Gitbook toolchain.
The documentation is then built to: /install/docs/markdown.
At time of writing changes to the API reference are not automatically populated to the Guide. Changed markdown files must be manually copied into the Guide's Github repo and submitted.
Extracting the API reference does not work automatically on Windows because the
maketoolchain is different.
Doxygen creates xml files from source comments in /install/docs/xml. The Python script generate_markdown_from_doxygen_xml.py converts these to markdown (and stores in /install/docs/markdown).