I’ve done a short video guide to contributing to the ArduPilot documentation
5 Likes
Thanks Tridge! PR linking this into the wiki here:
this is indeed very useful, thx a lot
and I immediately gave it a try 
(sadly the preview isn’t WYSIWYG, which makes it hard to get the formatting right by trial and error, you guys may have to polish)
1 Like
that’s fine. The preview tab does help, but it isn’t perfect. You can build and view the full docs in a web browser locally, but its quite a bit of effort to get setup, so I just showed quick edits on the video
this was certainly a good decision to not show this
I was looking for a button/option to at least not show the modifications in the preview but didn’t find it, maybe it was just my fault
anyway, very useful video, thx
very useful, thx.
I agree, as others commented, that it is a pity GitHub made up a proprietary “RST” language instead of a wysiwyg editor or , even better, to accept .dot or .doc or .html formats. Of course GitHub is meant for developers to code programs, not to edit documentation.
Eventhough an average user might find it too difficult, it is anyway very useful to open this possibility to everyone.
Thanks
It’s not GitHub that dictates use of ReStructured Text, it’s Sphinx, the underlying Python based engine with which the Wiki is built. Also RST is not proprietary, and widely used in the OpenSource community like Linux.
But yeah, agree, difficult to deal with unless making simple changes. There are wysiwyg RST editors though, like plugin for NotePad++ or RestView on Win or ReText on Linux, see http://ardupilot.org/ardupilot/docs/common-wiki_editing_guide.html, although again not necessarily trivial to use for the non developer.
I will try Notepad++ as I’m quite familiar with this editing tool. Thx.
I used to be part of the editor group when DIYD was our home. I have been off the net for a while due to an accident, and am getting back into UAV building.
Editing on GitHub is so much more difficult than WordPress was (for me). Is there a simple text editor/converter for a newbie to use? I would like to update some of the pages I authored that are still in the wiki, but they contain links, images, etc. I have no idea how to create that in the GitHub wiki.
Edit There are references in the GitHub help pages to a “wiki toolbar” that converts it to code for you, but I don’t see that when I go to edit on GitHub.
Thanks,
Dave
yes, it is harder, sorry. It does make it much easier for us to track stuff over time though, and we have a lot less security issues (I used to spend quite a bit of time patching security issues in wordpress and defending against active attacks).
there are really two ways. One is what I show in the video, which is for simple quick text edits.
The second is to do a full git clone of the repo and to learn to “build” the docs yourself. Then you can do lots of edits locally and test them out before submitting a PR.
It does take quite a lot of effort to learn to do the 2nd type of editing, and all I can do at this stage is apologize for that.
Cheers, Tridge
I am starting to figure it out. I installed the GitHub Desktop and Atom to make the changes locally. If I submit changes (commit?) can I put links to shared files so that they can be added to the wiki. Part of the problem with the page I am updating is that the image links are broken. Some of them have been saved to GitHub, but others are pointing to Photo Bucket, which doesn’t allow image hosting (for free) anymore.
Also, do you recommend a package in Atom for easy Markdown translation? I am using Markdown Writer, but it is pretty slow.
I’m embarrassed to say that I had to lookup what Atom is. I am an old-school emacs user. Now that I know what it is, atom actually looks pretty nice.
I see there is a sphinx plugin for atom:
the ArduPilot docs are written in sphinx, so that sounds ideal. I can’t tell you if its any good though, as I only discovered what atom is 30 seconds ago …
When I went through the GitHub tutorial, it referenced using “Markdown”. Should I be using Sphinx instead? I did notice that the syntax for embedding/linking images was different.
Thanks,
Dave
Yes, Sphinx. Thanks for getting back into this!