#getting library examples and documentation into Learn Guides

1 messages · Page 1 of 1 (latest)

gusty plover
#

@wintry sparrow @dense monolith @fading nest We had talked earlier about the large number of library examples that you folks have been writing up. At that time I suggested writing them up in Adafruit Playground notes, which might be linked to from Learn Guides.

You know that there is a way to link code from a repo to a Learn Guide. We use this all the time: code in https://github.com/adafruit/Adafruit_Learning_System_Guides is used for bundles and code examples.

But I remembered there is also a mechanism in Learn Guides that allows markdown text (to be embedded into guides. . We use this very little right now. Here's an example. Much of these two pages are actually from a repo:
https://learn.adafruit.com/i2c-addresses/the-list
https://learn.adafruit.com/i2c-addresses/troublesome-chips
Repo is:
https://github.com/adafruit/I2C_Addresses/ See the .md files there.

What this means is that, for instance, a .md file could be written for a library example, and then in a Learn Guide, both the code and the markdown could be embedded on a page. That would make the example more visible and also its documentation.

We don't have to do this for every single example, of course, but it's a convenient way for the doc and the code to be maintained together and then the Learn Guide content would be updated automatically.

wintry sparrow
#

Interesting! I knew you could enter markdown into learn guides with one of the elements on the page, but not that you could embed markdown files that exist in github. I like the idea of having the documentation content stored in a repo with the git version control. This could potentially also be helpful to people who are finding the examples in the repo but don't necessarily know about the learn guides. Today they'd basically miss out on the guide, but if we have a md file with the example it can contain the most relavent documentation directly there as well as potentiall a self link back to the guide if there is additional content not from the embedded md file.

fading nest
#

Does it support both markdown and reStructuredText? Since that's what we currently use for documentation in the repo?

gusty plover
#

it supports only markdown: the markdown is rendered by some javascript components.

fading nest
#

Do you know what library? It's possible it could get switched out. It would allow on type of file in both places...

gusty plover
fading nest
#

They don't need to, but could be helpful to make the info on RTD more complete

gusty plover
dense monolith
#

@gusty plover The way I keep my code examples in my personl repo (filled with tons of examples) is with a code.py more like a project bundle. I usually include whatever libraries an example is using too. More like a embedded project bundle. Not sure if playground has the ability to link project bundles in the way folks can set that up in Learn Guides, but that would be helpful for playground too.

#

Having the ability to directly embed a github code.py would be nice. Sounds like with this method I'd have to duplicate code.py into a code.md?

gusty plover
#

I am not talking about Playground here, I'm talking about Learn Guides directly. We'd author the learn guides, but that would be easy, because we could just link directly to the example .py and .md files

dense monolith
#

Oh you're only talking abou the adafruit_requests examples. Hmmm the md files would still have to be updated manually with every update for an example? That's a bit of additional work and would need to be updated any time a simpletest example is updated? Makes maintenance a bit more work.

gusty plover
#

The .md files would be documentation of the examples. They would not include the source code. Depending on how much the example is updated, the doc might not have to change very much or at all.

dense monolith
#

For learn guides that have snippets split up and explained there's no easy way to keep those updated. Individual md's for sections does sound like an easier route to keep those parts updated. I like the idea. It's just a bit more manual work. Honestly I can't think of a better way to do it. Sounds good to me.

gusty plover
#

i'm not suggesting individual .mds for each snippet. I think the snippet stuff is a bit overrated, and it's very hard to maintain. Thoroughly commented examples can substitute for snippet explanations.

dense monolith
#

I'm all for that but the snippet style in learn guides is extremely beneficial to beginners. They do need those explanation sections.

#

I suppose it will help more to see how it's actually used with an adafruit_requests example (simpletest) and we can go from there?

gusty plover
#

snippets are fine in the .md too. It is more work to maintain but documentation is really a necessary part of writing code

dense monolith
#

ugh paperwork 😖

fading nest
#

@gusty plover I'm happy to take a stab at this. Is there a repo that you think would be a good one to start with?

Maybe something simple like NTP since it's really just the one method?

gusty plover
fading nest
#

I didn't think it was to replace RTD

#

So for example.py, we would have example.md, which would explain the example, what it's doing and how it works?

gusty plover
dense monolith
#

Is there another example you can reference as a template? The I2C address one is mostly just a list. I can come up with something and just slap it down on paper and you can all review it and we can refine a template to go from there?

#

I think FoamyGuy would be the best person to make the first one. He has a better idea of what's expected and how to translate that to an .md for documentation. I volunteer FoamyGuy as tribute.

fading nest
#

I'm also happy to do it. There are also plenty of online editors that will save stuff as markdown

dense monolith
#

I started on a new playground note (for the rocket launch api example) and was able to successfully embed a .md file directly into the note. However, I then changed and updated the .md file and it's not changing in the playground note. It's cached somewhere, perhaps in my browser or on the adafruit site. That's going to be cumbersome to work with.

#

It forced me to sit down and write something, anything, so I'm writing a guide on how to use Adafruit_Requests for the absolute beginner called "Web API's & You".

#

It's the kind of guide I wish existed when I first started using adafruit_requests.

gusty plover
fading nest
#

Is it supposed to fetch it on every page load?

gusty plover
dense monolith
#

I attempted to use a .py file but it didn't work. Perhaps because my pathing has spaces in the name which are substituted with %20's. Yeah it's still not updated, unsure if it's a browser cache.