Normalize the git repository

Twilight-Logic / AR488

AR488 Arduino GPIB Interface

GNU General Public License v3.0

215 stars 62 forks source link

Normalize the git repository #15

Open douardda opened 3 years ago

douardda commented 3 years ago

Hi, this project looks very interesting, and I'd like to help for an ESP32 version of the code. However a few things look a bit strange with the way the git repo is managed:

why not use tags for published version?
why add the zip file of the "last" version (can be omitted is properly tagged), as well as
why keep old version as a bunch of binary (zip) files instead of using what git is made for (using tags)?
it would be also nice the add the sources of the documentation instead of the pdf files directly (using a markdown, ReST or even a tool like sphinx to manage the documentation).
ideally, binary files (docs and firmwares) should be automatically built (eg. using travis-ci)
it would be nice to have the work in progress for other platforms (eg. esp32) available as branches.

Would you consider these improvements? Would you like some help for this?

Thank you David

Twilight-Logic commented 3 years ago

David, thank you for your kind offer of help and sorry for not responding sooner. I was not ignoring you! Have only just seen your comment. It would be useful if GitHub notified me when a new issue was opened! I would certainly consider such improvements and your offer of assistance is greatly appreciated. You have already mentioned a couple of tools which I will explore so thank you for this.

douardda commented 3 years ago

Hi,

I've started doing some cleaning stuff in https://github.com/douardda/AR488/tree/normalize I've removed all the zip files (as well as the Contributed directory which IMHO should be merged with the main code; which I ma try to do later on).

For the doc, it would be handy to get access to the source fie of the PDF you publish, so that I can try to convert it as a sphinx project.

Also note that in my fork, I have created tags for versions I could easily identify in the git log.

douardda commented 3 years ago

I've started a sphinx-based doc (copy pasting from the PDF). You can have an idea of the result here: https://sdfa3.org/david/ar488/

It's a straight sphinx config (default theme, nothing tuned or adapted).

Note that sphinx can also generated PDF files out of the box

douardda commented 3 years ago

Got the main documentation converted to sphinx in this branch (in the docs/ directory); the HTML result is visible on the same URL.

It needs some work to make it look a bit better, but it's a nice starting point IMHO.

Meanwhile, I have also played a bit with github actions to build the firmware automatically.

https://github.com/douardda/AR488/actions

For example, generated firmware files for my latest git revision are listed on:

https://github.com/douardda/AR488/actions/runs/1351644598

For this I am using platformio to compile the firmware for different boards (this works in a branch of mine in which I am porting the code to work on a STM32, here a Nucleo F303K8 I had laying around, but that's another story I'll talk about later :-) ) I've use the example workflow from platformio as starting point.