Develop.arduboy.com - Information

A new sub-domain is being maintained that includes a programmer’s reference for the Arduboy Library.

http://develop.arduboy.com

Content

As of posting this, only the API documentation is available. These documents are generated from the work of the developers contributing to the core library on Github. In the future, guides and tutorials can be found through this domain.

Front Page

Currently the front page holds reference documentation generated from the stable branch of the Arduboy Library.

Other Branches

List of all branches.

Currently the stable, develop, and master branches are available. Other branches may be documented as needed or requested.

6 Likes

I don’t like the colour or the assumption that everyone who uses github also uses git.

Otherwise good move.

1 Like

Minor nitpick, the “Running on a development board” section is outdated or incomplete, it should mention the boards.txt switcher can handle that automatically.

2 Likes

Colors can be changed with the Doxyfile found in the develop branch. It’s essentially a no-work-into type of design, and all effort was put into the automation, so we do need some work on the visuals. Doxygen can easily take a CSS file, I’ll work on a repo just for the doxy styling.

As for github, it’s where our project is hosted, and github is just the url. Would you like more commands for switching branch’s via the git binary? I’m not sure what you mean there : D The directions would be just about the same if our host was bitbucket, I think, I’ll re-read the document and see if I can get at what could be better. Feel free to suggest a change with a PR as well.

Thanks, the info at the beginning of the site looks not so great to me as well. It’s pulled from the README.md file held on repo, and doxy interprets markdown a bit different than github does. As time goes on it would be nice to come up with a better looking file, but everything is all on Github, so forks and pushes are always welcome.

I’ll add a little section about how to start to change the look of that site via git and github.

Having documentation is nice but the Arduboy library has remained at V1.1 for well over 5 months, and now the display does not work properly with the latest Arduino IDE V1.6.10 release.

Why work on documentation when the library has essentially become “abandonware”?

4 Likes

I mean, some of us don’t use the git command line, and don’t actually have git installed on our computers.
Currently your only installation instructions consist of
$ git clone https://github.com/Arduboy/Arduboy.git.
Which makes the assumption a person downloading/installing the library has git installed on their computers.

Whenever I grab a new vesion of the library, I do so by downloading the zip form straight from github, unpacking it and placing it in the correct location for Arduino Studio. I think some people (particularly the less experienced, the less technical or people who prefer GUIs to command line) might benefit from an alternative set of instructions telling them how to do it without having to use a command line interface.

1 Like

Definitely recommend getting into source control, even if not Git.

I haven’t used The Tortoise plugin for Git but for other projects where I am required to use Windows I commonly use TortoiseSVN for Subversion or for TortoiseHg for Mercurial. Might be worth a shot if you want a GUI but don’t want to learn the command-line version of Git.

https://tortoisegit.org

I have not seen any fantastic GUIs for version control on Mac but SourceTree isn’t bad and I think it might be cross platform between Windows / Mac.

Not sure on Linux so I just tend to use command-line tools there.

1 Like

I presume that was supposed to be directed at me and not a general comment?

My point isn’t just about what I choose to do for simplicity, it’s that some of the less experienced users may not be happy with command line stuff and for many it would be daunting enough trying to learn how to program in the first place, without added technical stuff before they’ve even got the library working. I for one certainly couldn’t imagine myself using a command line tool when I was first learning to program. Heck, I probably still didn’t know what a command line tool was and had probably never seen one.

On a personal note though, I’m not working on a project big enough or with enough people to require any more source control than what the github website itself provides, the time spent installing and studying a different source control system would not in any way speed up my development process.

I can download current versions of code, I can add new commits with proper comments and I can request/merge PRs. Those are all the Source control tools I need.

I would totally learn some version control if you are programming a lot. Whether it’s mercurial or git or any other choice. When working with a project, or on a project that is maintained by a group “at large”, they will choose a way to manage the project that participants in the project will want to use in order to participate.

The Arduboy project uses the git binary, and the source is visible via github.There would be no other way to push a change to the Arduboy Library source if one wasn’t using Git, so one would need to learn git to work on the library.

However, for “users”, the guide needs an update. There should be a sub section about using the Arduino IDE instead of git or a zip.

Feature?: we could also write an ansible play to package the zips from git when there is a commit. This is something we can, and probably should do, and link these from the front page.

Please see the develop branch of the Github page for the “rolling-release” of the Library. That is where you will find the most up to date version of the Arduboy Library, where the development is happening.

A commit of the patch for the screen can go into the 1.1 release, and that is probably what we will do instead of iterating the version. See the related github commit for the discussion.

That’s great, but when is this “rolling-release” finally going deemed stable, and be merged to the stable branch and released and tagged so that the Arduino Library will pick it up, allowing “regular” users and developers to use it? What good is a development branch if the changes are never frozen at some point and made generally available?

And I have to ask (as I have previously elsewhere): If branch stable contains the latest stable release and branch develop contains new development, what it the master branch supposed to be used for?

Less experienced users should be using the latest official stable release and install it using the Arduino IDE’s Library Manager, as detailed in Step 2 of the Quick Start Guide.

For the record, [quote=“Pharap, post:2, topic:2035”]
I don’t like the colour or the assumption that everyone who uses github also uses git.
[/quote]

Function before form, when we have a chance to reskinning it with some CSS it will develop a similar purple type look and feel eventually. This has been a project @ekem has been working on for some time so I imagine it’s great for him to finally get feedback on it.

For the record, I hate command line git and @ekem loves it. I go to github and download the zip file, this makes @ekem and probably others kringe, but it’s reality so we have to deal with it. Just so we know where we stand, there will always be lots of options for users. This documentation is meant more for how shall I say it “experienced” type developers who would use something like this.

Our lesson plans and tutorials will be more for the beginner and not require you to use any command line tools.

We will be having an update soon that works with the new IDE. And yes things have slowed down on the development of the library, but it should be expected that it evolves to some kind of steady state after all necessary features are there and has been properly optimized. You’re welcome to push updates if you like we will continue to monitor it.

But frankly, you’re talking to me who is full well in the camp of “it works, good enough”. We want to give people as many paths and options they have. Obviously a library that doesn’t work with the latest IDE is a problem, and we will fix that, as we will fix other bugs as we discover them.

@Dreamer3 was leading heavy development of the library, and did a bulk of the work. We wouldn’t be anywhere near this far if it wasn’t for him and others who really wanted to see a quality library instead of a bunch of copy-paste code from other libraries.

1 Like

I hope people don’t mind, but I decided to leave a general reply and simply quote who I’m referring to in turn since it seems like several people’s replies were of a similar nature.

That’s kind of the point, in 4-5 years I’ve never yet needed to do that, I’ve only ever worked on a team of 2-3 people, so I’m going to keep doing what works until the requirement for something different arises.

Actually I helped modify a pull request that was supposed to have been merged once (wihtout using git), but for some reason yyyc514 closed it and resubmitted it himself so it shows up as if he had done it himself rather than the two people who actually worked on it.

Either way I probably won’t be assisting with the Arduboy Library again. At the time I wasn’t particularly aiming to assist with the library anyway, my primary aim was to assist my friend.

Ah, now we’re getting back to the main point. I partly agree depending on what sort of information would be included/how the tutorial would be handled. Either way it sounds more user friendly than trying to convince potentially non technical people the command line is their friend.

Also sounds like a good idea. (Not that I know anything about ansible or how easy it would be, but the results at least sound handy).

So hang on a minute, are you saying that such information doesn’t belong with the documentation?
If yes, does the git command have any business being there, and if not, does that mean you’re proposing part of the contents of the quick start guide should be included with the documentation?

True, but I couldn’t find fault with the function, hence the [quote=“Pharap, post:2, topic:2035”]Otherwise good move.[/quote]

For the record, I don’t hate it, I just can’t justify using it since I don’t work on any projects of a large enough scale to require it, either in terms of code size or group size. Like you I just download a new copy of the latest branch in zip form and work with that.

I beg to differ on this point. I think many inexperienced users would also use the documentation, even if not straight away. I remember when I was first learning to program MSDN was easily my most visited site, later tying with StackOverflow.
On the other hand, if the documentation were only used by experienced users, I would have thought they’d already know how to get a copy of the source code, or at least would know/be able to figure out what git command to use to acquire it if they had git installed on their computer. The kind of people who wouldn’t know what command to use would be the ones who wouldn’t have git installed.

https://github.com/Arduboy/Arduboy/blob/stable/README.md Hey hey, @Pharap, would you mind taking a look at this README.md and see if you have any feedback :smiley: I’m doing some updates with your suggestions in mind.

1 Like

Yup, or at least only as a section near the end, not the primary purpose.

Again, the Git command should be there just as a minor reference, if at all.

Here’s a GitHub pull request I made for what I feel is a suitable first cut for README.md

Well, I’ve got two people asking me to read and give feedback on two very different readme files here. I’m going to read and examine both and then make another reply (or possibly replies) with my thoughts (hopefully soonish). Chances are I’m going to advocate features of both rather than simply claiming one to be better though.

1 Like

Firstly I’ll say this focuses more on @MLXXXp’s edit since it was more drastic (in both good and bad ways), but I will say before I begin that I think all of @ekem’s additions were beneficial, but it was less drastic, so it’s not really fair to compare the two edits as if they were competing/conflicting since they were taking very different approaches and aren’t entirely mutually exclusive. Also I appologise in advance for taking so long and for writing such a long and in depth analysis, but old habits die hard and I kept stopping to look at the comments on the pull request (which I may get involved in at some point).

I like the introduction of @MLXXXp’s version since it gets straight to the point of installation, which is what most new users reading the readme will want to find out. I also like the external links that were added as that will help users that stumble upon the project by accident or were directed there from elsewhere.

However, I don’t like how it only directs people to the quick start guide and does not include the advice about using the Sketch > Include Library method within the readme itself. I agree that some of the install information in the readme might have been more than necessary, but I don’t think all of it should have been removed, I think the bare minimum should have been kept and the link to the quickstart guide should be there as a sort of “if this was not enough”/“for a more in depth guide, please see here” type thing. Certainly I don’t think the information about the examples or running on the development board were needed, but I think the readme should contain enough to get the user up and running. This is what @ekem’s edit was aiming for and I think that was a good thing.

Side point, feel free to skip:
(I’d also like to point out that the introduction of the quickstart guide is heavily about codebender, which might be offputting to new users. Note that at time of writing only 1.7k people have clicked the codebender links, whereas 3.0k have clicked on the arduino studio download page. I think this on its own should be a good indicator of what kind of information deserves pride of place. It’s also to note that 1.0k clicked the link to the zip of the stable version, which is clearly said to be not required if the Sketch > Include Library > Manage Libraries method worked, indicating it’s a very reliable way of doing things)

The additional information regarding the develop branch not being stable or debugged is also quite a vital addition.

Since the @MLXXXp edit removes a large chunk of what was there before, a lot of minor typographical errors have been removed with it, but one glaring problem is still present (and I know people will groan at me for this one).

The grouping of ‘C/C++’ in the introduction.
Despite what people think, C is not a subset of C++, they only partly overlap. Instead of ranting about why this is important, I am going to direct anyone who disagrees to the wikipedia article on the matter. If you can get through the whole article and still feel the two are still ‘essentially compatible’ then I’ll gladly listen to your reasoning, but hopefully the examples in the article will be enough to prove that someone who has only ever had experience in C might feel that such a description is a bit of a lie. (If you’re feeling brave, there’s a much more in depth analysis available).

The only problem with this is that you have the same information in two different places. If the information changes, you have to remember to update it everywhere that it’s documented. This is one reason why README.md needed to be updated. The Quick Start Guide was up to date but nobody bothered to update README.md to match. By having README.md just refer to the guide, you often only have to change one document. And, making changes to README.md involves editing, committing changes, updating the version number, then tagging/releasing a new stable version of the library.

You can’t use link clicks as an indication. A good many of the clicks on the .zip file were made before the library had been submitted to Arduino and was made available via the Library Manager. Before that time, the .zip file was the best way available.

After the Library could be installed via the Library Manager, I updated the Quick Start Guide with the new instructions, but this didn’t reset the click count on the .zip file. I suspect that proportionately very few clicks have been made on the .zip since then.

Yes, I was contemplating changing this, but my goal at the time really wasn’t to question the accuracy of that kind of thing. I just left that part as is.