Comments (24)
from wakaama.
This looks very informative. Thanks a lot!
I am starting to think we should have this kind of information stored close to the source code, and keep it up-to-date. Maybe this a good reason to start introducing some proper dev docs, e.g. a Sphinx based one, have it hosted somewhere?
from wakaama.
Probably a detail π
, but about Core Link
I understand that :
Core Link
Data Format is introduced in LWM2M v1.0.x. (See : Β§6.4 Data Formats for Transferring Resource Information) which is used for Register/Update Request and also for Discover Response.Core Link
Data Type was introduced in LWM2M v1.1.x (See coreΒ§Appendix C. Data Types (Normative)) This is a possible data type of LWM2M resource in Object Model. (Not sure but I think it is used in Gateway object π€)
Note that :
- LWM2M v1.2.x also add
SenML-ETCH JSON
andSenML-ETCH CBOR
for Composite Operation. (I don't know this part so much...) - LWM2M v1.1.x also add
Unsigned Integer
Data Type. AFAIK, there isn't new Data Type in LWM2M v1.2.x.
from wakaama.
I started in Californium also with Wikis. After some time I moved the version specific information into Markdown along with the source in the modules. In some cases I also collect the version specific information history and put that always on the "main", so that it's easier for users to see the changes.
from wakaama.
I vote also for developer documentation in the repo.
As for the markup language I'm fine with Markdown or with reStructredText.
from wakaama.
It seems that this discussion here is not directly related to the topic of the issue. I'm going to open a new issue, where we can come to a conclusion.
from wakaama.
@rettichschnidi @mlasch @LukasWoodtli
from wakaama.
Nice! Thank you for sharing!
from wakaama.
@sbernard31 Nice! Thanks for the clarification.
I plan to collect all the feedback from the community and then update the table.
from wakaama.
I am starting to think we should have this kind of information stored close to the source code, and keep it up-to-date. Maybe this a good reason to start introducing some proper dev docs, e.g. a Sphinx based one, have it hosted somewhere?
I agree.
At Leshan we put it in wiki :
- https://github.com/eclipse-leshan/leshan/wiki/LWM2M-Supported-features
- https://github.com/eclipse-leshan/leshan/wiki/LWM2M-1.1-supported-features
but this is maybe not so smart because this information is strongly tied to the state of the code, so probably smarter to put in code repository. Same for documentation. (And we did same error in Leshan putting documentation in wiki too π)
from wakaama.
Could we host the rendered documentation somewhere on Eclipse infrastructure? Any experience with this?
from wakaama.
Could we host the rendered documentation somewhere on Eclipse infrastructure? Any experience with this?
The simple way is to write your documentation in Markdown in your code repository and so you can use default github markdown rendering , Iike with current README. Personally I recommend this way.
If you want to do more (which will be probably more work and not sure if there is more benefits), you can eventually host your documentation in the Wakaama website ?
- the website : https://eclipse.dev/wakaama/
- the repo of the website : https://github.com/eclipse/wakaama-website
Maybe before to go on that direction, it could make sense to ask some advice to eclipse IT : https://gitlab.eclipse.org/eclipsefdn/helpdesk
from wakaama.
I think both ways have its own pros and cons.
- wiki: more native integration with GitHub infrastructure (e.g. issues), better rendering, collaborative editing
- MDown: better tie to the code, easier to maintain, keeps doc inside the repo
Seems wiki may be better for Wakaama users; while MDown is better for Wakaama developers.
Bottom line.
I vote for MDown for now, as far as we do not have a lot of external users yet.
If/when the situation changes - we may render MDown-based docs to the Wiki or Web-site or whatever.
from wakaama.
@rettichschnidi I hear advice to not use MDown for Docs. And use the reStructuredText text instead.
Like these articles: https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/ and https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/
And this discussion on Reddit
This also makes simpler integration with Sphinx in future.
(Personally, I don't have any experience with reStructuredText.)
from wakaama.
That may be a misunderstanding, github renders markdown on viewing via a browser.
The README.md is shown, when browsing the "code". Other ".md" may be referenced or rendered by click on them.
The point with the variants and dialects is easy, you need to stick to the parts supported by github ;-).
And sure, there are limitations, but on the other side, it's pretty easy and works well.
from wakaama.
@rpolitex thx for sharing this. π
I thought Github was only able to render markdown. π€¦
But Reading : https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
Developers prefer it because GitHub supports it, though GitHub supports 9 different markup languages, including Asciidoc and reStructuredText.
So I quickly tested for :
- reStructuredText : https://github.com/sbernard31/leshan/blob/test-markup/test-reStructuredText.rst
- asciidoctor : https://github.com/sbernard31/leshan/blob/test-markup/test-asciidoctor.adoc
And indeed they seem to be (at least partially) supported too π€© .
So I change my recommendation π :
The simple way is to write your documentation in
Markdownany markup language supported by github in your code repository and so you can use default githubmarkdownrendering , Iike with current README. Personally I recommend this way.
About markdown, I already faced some limitation (or rendering issue outside of github because of lack of standard), so I can easily imagine that it could have better choice. (but I didn't test it)
from wakaama.
I had a first impression for reStructuredText.
There may be others with more sophisticated opinion, but for me it looks very similar to markdown. It comes with a clearer structure, but my impression is tables seems to be not the strength.
One pain with that approach (painting in ASCII) is to recommend to use Chrome instead of Firefox.
(At least my Firefox breaks such ASCII paints ;-( ).
from wakaama.
IMHO, Tables are pain in both, reStructuredText as well as in Markdown. However, in Sphinx, it is quite easy to include a .csv/.tsv file as table. I found those quite easy to handle using a regular spreadsheet editor (like LibreOffice).
Going this way would require a hosting for the rendered Sphinx documentation however. Something I think is quite easy to do, and totally worth.
from wakaama.
I've collected some asciidoc experience in the past days.
For me that's very promising, see mobile-bienenstock-waage (German only).
from wakaama.
The syntax of asciidoc looks nice. But I would prefer to be able to use a documentation system like Sphinx even if reStructuredText is not my favorite markup language.
from wakaama.
I didn't know sphinx and I have no idea if asciidoc is better than reStructuredText but just for completeness, it seems there also tooling with asciidoc :
- https://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc.org/-/blob/main/awesome-asciidoc.adoc#user-content-publish
- https://pandoc.org/
from wakaama.
I didn't know sphinx and I have no idea if asciidoc is better than reStructuredText but just for completeness, it seems there also tooling with asciidoc
I don't know about the tooling and ecosystem around asciidoc.
But Sphinx is well known by a lot of developers and widely used. See the (incomplete) list of projects using Sphinx in the documentation: Projects using Sphinx.
There are also a lot of extensions to Sphinx: tooling, plug-ins, themes...
But I'm not hooked to Sphinx. I can live with other solutions, too. I just feel that Sphinx would be a good solution.
I would also not add a lot of tooling from the beginning. We should just start to document things by adding markup files to the repo. But it would be cool if we could use a documentation tool as soon as we have some documentation pages put together.
from wakaama.
I would also not add a lot of tooling from the beginning. We should just start to document things by adding markup files to the repo.
π
I just feel that Sphinx would be a good solution.
On my side, I think this is up to active committers to decide and I didn't see any veto about using reStructuredText/Sphinx. π
from wakaama.
See also #732
from wakaama.
Related Issues (20)
- Block-wise transfer on observe response? HOT 1
- How should we document Wakaama HOT 9
- server write operation , response COAP_400_BAD_REQUEST HOT 2
- Moving from Master to Main HOT 4
- Election of new committer HOT 9
- Option to transfer the Wakaama repository to its own organisation HOT 8
- How to use the wakaama library for Espressif HOT 5
- Question regarding the appropriate license for this project HOT 1
- Support of send operation for single resource data with TLV format ? HOT 10
- Is Leshan ready for production usage ? HOT 2
- Inquiry about CoAP Fetch Functionality Implementation HOT 3
- Client SEND operation does not use fragmentation leading to oversized CoAP packets
- Fixed buffer size in senml_json_serialize limits handling of multiple resources HOT 1
- Build Fails if LWM2M_RAW_BLOCK1_REQUESTS set HOT 4
- Compile server&client example with DTLS HOT 1
- Include other libraries in examples HOT 1
- Wakaama logs arbitrary bytes to stdout
- client example building issue HOT 5
- Layered Architecture HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from wakaama.