Skip to content

Added documentation for modes #52

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 3 commits into from
Jul 13, 2020
Merged

Added documentation for modes #52

merged 3 commits into from
Jul 13, 2020

Conversation

evaherrada
Copy link
Collaborator

@tannewt This should clear up #16. I tried to document them where they were defined, but sphinx was not cooperating

tannewt
tannewt requested changes Jul 1, 2020
View reviewed changes
Copy link
Member

@tannewt tannewt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please explain what you mean by not cooperating. It'd be best to document them where they are define.

adafruit_bno055.py
| ``sensor.mode = adafruit_bno055.ACCONLY_MODE``
| replacing ``ACCONLY_MODE`` with the mode you want to use

.. data:: CONFIG_MODE
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this render it on the module or class?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Class. Here's what it looks like. I can have it render on the module, so it starts right after the author, but I thought this way was a bit cleaner.

docs

@evaherrada
Copy link
Collaborator Author

@tannewt So I wasn't able to get it to render that way. I'm not sure why, but I'm not very experienced with autodoc or sphinx, so there's probably a way to do it that I just don't know about.

I tried putting comments with #: on the same line and putting docstrings with just text and with .. data:: after the lines and none of that worked.

@siddacious
Copy link
Contributor

@dherrada I use this tool to make tables for RST docs:
https://www.tablesgenerator.com/text_tables

I'll look for an example of when I used it.. 👀

@siddacious
Copy link
Contributor

@dherrada The HTS221 docs use it:
https://circuitpython.readthedocs.io/projects/hts221/en/latest/api.html
from
https://github.com/adafruit/Adafruit_CircuitPython_HTS221/blob/master/adafruit_hts221.py#L102

@evaherrada
Copy link
Collaborator Author

evaherrada commented Jul 1, 2020 •
edited
Loading

@siddacious I think there may be an example in this library already. The issue I'm currently running into is that it'd be better to document the modes where they are defined, but I can't figure out how to tell sphinx to do that.

Also, FWIW, the tables render a lot better in rtd if you put them in a code block because they rely on a monospaced font to look right

@evaherrada
Copy link
Collaborator Author

evaherrada commented Jul 1, 2020 •
edited
Loading

Oh... Huh. I wonder why it didn't work like that here

Edit: looks like they need a line on the top and bottom to work right

@tannewt
Copy link
Member

tannewt commented Jul 2, 2020

I tried putting comments with #: on the same line and putting docstrings with just text and with .. data:: after the lines and none of that worked.

So if you did a triple quoted comment after the definition it didn't work? That may be a class member thing only.

@evaherrada
Copy link
Collaborator Author

Yeah, I think that may be the case

@evaherrada evaherrada requested a review from tannewt July 10, 2020 17:12
@evaherrada evaherrada linked an issue Jul 13, 2020 that may be closed by this pull request
mode command: docs vs. implementation #16
Closed
@evaherrada
Copy link
Collaborator Author

@tannewt Moving forward, what would you like me to do with this PR? I know the way I have it isn't really ideal, but I'm not quite sure how else to do it.

tannewt
tannewt approved these changes Jul 13, 2020
View reviewed changes
Copy link
Member

@tannewt tannewt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is fine. I don't want to block you on adding documentation even if the location is less than ideal.

@tannewt tannewt merged commit 2064bdb into master Jul 13, 2020
adafruit-adabot added a commit to adafruit/Adafruit_CircuitPython_Bundle that referenced this pull request Jul 17, 2020
@adafruit-adabot
Automated update by Adabot (adafruit/adabot@20501cf)
1c03e68 
Updating https://github.com/adafruit/Adafruit_CircuitPython_BNO055 to 5.1.0 from 5.0.2:
  > Merge pull request adafruit/Adafruit_CircuitPython_BNO055#52 from adafruit/docs-update
  > Merge pull request adafruit/Adafruit_CircuitPython_BNO055#54 from adafruit/i2c-gpio_example

Updating https://github.com/adafruit/Adafruit_CircuitPython_Fingerprint to 2.0.0 from 1.2.2:
  > Merge pull request adafruit/Adafruit_CircuitPython_Fingerprint#21 from jerryneedell/jerryn_fingersearch

Updating https://github.com/adafruit/Adafruit_CircuitPython_BLE to 7.0.3 from 7.0.2:
  > Merge pull request adafruit/Adafruit_CircuitPython_BLE#95 from madgrizzle/patch-2

Updating https://github.com/adafruit/Adafruit_CircuitPython_Pypixelbuf to 2.1.2 from 2.1.1:
  > Merge pull request adafruit/Adafruit_CircuitPython_Pypixelbuf#26 from dunkmann00/dotstar-brightness

Updating https://github.com/adafruit/Adafruit_CircuitPython_ServoKit to 1.3.0 from 1.2.2:
  > Merge pull request adafruit/Adafruit_CircuitPython_ServoKit#21 from razvanphp/master
@evaherrada evaherrada deleted the docs-update branch January 27, 2022 18:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@tannewt tannewt tannewt approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

mode command: docs vs. implementation
3 participants
@evaherrada @siddacious @tannewt