-
Notifications
You must be signed in to change notification settings - Fork 13.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
ADS1115 Update docs - for discussion #21638
Conversation
@bkueng I would appreciate your review of this, but more importantly, I'm wondering what we might practically do to allow this to be reused or used in user docs. I think this is sufficient for module docs - if you're looking at the driver then you probably know what an ADC is, and why you want it, and how you find out details about its usage. But in user docs you know a lot less, which is why we have the peripherals section - such as https://docs.px4.io/main/en/power_module/ Ideally in docs for this case I'd have a top level ADC page that explained
The top page might link to device specific information, though usually if there is much I put that in its own page. That information includes:
What I'm after is a way to automate getting information about what we support as it arrives, and as it is dropped. How we might do this really depends on what can be inferred automatically and what needs to be specified. I mean it might be that we could get 99% of this by running a module_docs script that greps each module to get the params and the key for kconfig, uses conventions like So I was thinking a script that ran across the docs and built a representation of all the information that you might need for user docs. Then use that to build user docs, or pass to the docs system to generate. What do you think? What fields would we need to have in source docs to be able to extract things like "enable params", and where would those live? Close to the driver docs ideally. Imagine I'm doing the work as your minion :-) |
@bkueng I've been thinking about this a little more. It might be useful to export a whole lot of data in our current parsers as json or similar for easy parsing, and add a few more parsers. We can then generate data from that data and repurpose as makes sense. For example
With all that in json we could update module parser, for example to include the parameters, and also to make statements about board support like "Is in most boards by default, with exception of X, Y, Z, and is enabled using ABC params". With this info on hand we could more easily dual-generate user-facing docs or tools and whatever other docs we want in future from pre-extracted information. Even if I can't do that, having a JSON that shows me the essential information about added/removed/changed data in a module-centric way would make automated tracking of change easier. Don't know if you see that as worthwhile, or if there are better ways to achieve the same goals. It feels empowering though, and smart to separate data extraction and rendering. |
Another idea, render the description in user docs as user docs about the associated hardware, not about the module? |
Makes sense. There's some overlap with device manifests, and we should think about how/if to use the same information for a device configuration UI in the GCS (similar to actuators). |
Sounds good! I think you'd be best person to make specific design requirements on the extended possibilities. Is this PR otherwise good to merge? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good, can you run make format
?
Done. Thanks! |
There's still a failure:
Maybe we don't need to be that strict with line lengths, I just added it to be consistent with the source code. |
As you know, I prefer sentence breaks in our docs. But I think that as this is in source, we should have consistent rules. If this proves difficult we can revisit later. Fixed for now. Thanks |
This updates the docs for the ADC1115 ADC in order to make it clear:
It is a test case for similar changes I hope to make across the docs, and to explore what might be automated. I'll add that discussion in a separate comment.