it takes some getting used to, but it's grown on me. sphinx uses a similar style for their own docs, and it seems to work:
http://sphinx.pocoo.org/contents.html
Maple 0.0.9 Documentation Preview
(23 posts) (7 voices)-
gbulmer
ModeratorA few comments on
http://static.leaflabs.com/pub/leaflabs/maple-docs/docs-0.0.9-preview/language.htmlMaybe move the "Note for C/C++ Programmers" to a separate page?
It is very interesting information, but IMHO the language reference page would be more focused if it was, erm, well, er, more focused!?If the side bar is staying, delete the "Contents" block from the page flow.
Then the page could start with the "Maple Language Reference" table.
I'd suggest putting ASSERT into the table, maybe in a 'debug" section?
I'd also suggest putting in everything from the Arduino 'standard' library/language, and marking things that are not implemented.
For example:
"word" in data types, and say "not implemented" - it can have a link to a section lower down the page for an explanation.
"analogReference()" - "not implemented" and a link
Similarly:
* interrupts()
* noInterrupts()
* noTone()
* pulseIn()
* shiftOut()
* String
* tone()Put them in the Language Reference table, in the appropriate section, and mark which aren't there yet.
I'd suggest making a small icon for "not implemented" to ensure the table can be kept compact (the Leafab logo combined with the classic 'stop' sign?).
You might also think about differentiating between functionality on Maple Native, but not Maple; again a small icon?Personally, I'd like to be able to see at a glance which items in the table are just standard C/C++, and which are Maple/Arduino. I'd never bother reading any of the C/C++ linked pages (but others might), but I would want to look at the non-C/C++ standard things, which are mainly the library, a few constants, and typedefs.
There are a bunch of constants missing, from pinMode, which I'd prefer to see on the reference page, listed under constants, or under pinMode.
There are a bunch of integer types which I'd like to see listed in the reference: uint8, int8, uint16, int16, etc. They don't need to be one per line, or they could be alises of the actual type and listed alongside them.
There is some ambiguity about what is a language element, e.g. OUTPUT, and a language concept, e.g. a "Constant". One I can type into a program, and it compiles, the other is not.
IMHO there needs to be a clearer way to differentate between them. This applies to Array and Numeric types too. If you feel the need for Numeric Types use it as a sub heading, and put them all under it.
Strings needs work.
The C++ class is String, and that could be in the list of data types.
The concept of a C string is covered in the page http://static.leaflabs.com/pub/leaflabs/maple-docs/docs-0.0.9-preview/lang/string.html#lang-string
Maybe call it 'C character string', or use the Arduino reference "string - char array"?HTH
Posted 5 years ago # -
poslathian
LeafLabsThanks for all the great feedback. Now that we have a good foundation to build off of, it seems the steps forward for making the docs even better are really starting to pop out. Whereas before, the best idea for how to improve the docs was...uhh.."can you make it better?"
Well they were made better, and let me take this opportunity to publicly thank Mbolivar for putting these new docs together...put the credit where its due - which is pretty squarely on his shoulders. Awesome job and thanks!
Posted 5 years ago # -
gbulmer
ModeratorThere are some very serious errors in:
http://static.leaflabs.com/pub/leaflabs/maple-docs/docs-0.0.9-preview/lang/analogread.html#discussionIt takes about 0.8 microseconds (.0000008 seconds) to read an analog input, so the maximum sample rate using this function is approximately 1.3 million samples per second[1]
That isn't true. With a perfect configuration, using a system clock of 56MHz, enabling an ADC clock at its maximum of 14MHz, it takes, at least, 1 microseconds to read an analog input. The conversion time is further extended by sample time, which is 55.5 cycles of the ADC clock.
At http://static.leaflabs.com/pub/leaflabs/maple-docs/docs-0.0.9-preview/lang/analogread.html#fsamp
This is based on the current configuration of a 55.5 cycle sample time, at 72 MHz. However, the minimum sample time possible is 1.5 cycles, leading to a theoretical maximum of approximately 48 million samples per second (of course, doing anything with the readings also consumes cycles, so this maximum can’t be reached in practice).
1 microsecond would be based on the minimum of 14 cycles of a 14MHz ADC clock. The processor clock is divided down to get the ADC clock, it isn't used directly.
AFAIK, the actual time with the current setup is about 68 cycles of 12 MHz.Posted 5 years ago # -
gbulmer
ModeratorA small suggestion - is it possible to stop the paragraph symbol from appearing when my cursor sweeps over a heading?
I keep thinking something happened, and going back to see what happened.
{start rant:
IMHO it is drivel. It is the opposite of good visual design. Why on earth a dumb heading should attract attention is beyond me. It is pure nonsense. The sort of rubbish that visually-illiterate technologists do because they don't realise there is such a thing as taste or graphic design; the sort of folks who think that text should look 'exciting', even if it serves no useful purpose.
end rant}Posted 5 years ago # -
mbolivar
LeafLabsre: the paragraph symbol,
That's Sphinx's (the documentation generator we use) default behavior; here's an example page from the Python docs which does the same thing:
http://docs.python.org/release/2.6.5/library/os.htmlAs you've likely discovered, the paragraph heading is a link, which when clicked, takes you to an HTML anchor for the section. AFAICT the mechanism is intended to enable getting permalinks to sections without having a TOC at the beginning of every page. It's never bothered me personally, but I can see why it would be frustrating.
I've looked at the raw HTML, and the paragraph symbols are there, so it should be possible to redo the CSS, add some javascript, or something to keep that capability without having content appear and disappear, but it would take a little while for me to figure it out. I'm not much good with Web 2.0 design.
I will look into it, but I won't make you any promises about when a fix might get put in, given that it's not really what I'm good at.
Posted 5 years ago #
Reply
You must log in to post.