Wednesday, 2019-09-04

*** tpb has joined #tomu00:00
*** rohitksingh has joined #tomu00:15
*** rohitksingh has quit IRC00:37
*** rohitksingh has joined #tomu00:37
*** rohitksingh has quit IRC00:44
xobsmithro: No, but I'll look at it right now!00:57
*** rohitksingh has joined #tomu00:58
*** emeb has quit IRC01:06
mithroxobs: Thoughts?01:56
xobsmithro: I tried putting reviews down.01:57
xobsIt looks like you moved the documentation to the top of the functin.  Can we keep it above the thing it's documenting?01:57
xobsI really like having the registers' documentation immediately above the register definition.01:57
xobsIt means that whenever I change the register size, I update the documentation right away.01:57
mithroxobs: Sphinx and Migen are both just Python code and Python is super inspectable, so you can pretty much do anything and make anything work02:18
mithroxobs: Just a effort verse reward type thing02:18
mithroxobs: Was trying to stick with a non-customized version as possible for the initial thing to show you02:18
mithroxobs: For example - see this sphinx + argparse integration -> https://sphinx-argparse.readthedocs.io/en/stable/sample.html02:19
tpbTitle: Examples sphinx-argparse 0.2.5 documentation (at sphinx-argparse.readthedocs.io)02:19
xobsmithro: I'm having a lot of trouble understanding what Sphinx is.  The documentation isn't very good.02:20
mithroxobs: Sphinx is a documentation generation tool?02:20
xobsmithro: Okay, but what are its input files?  I thought its input files might be Python, but it seems like its input files tend to be these .rst files.02:21
mithroxobs: Documentation is written in docutil / rst -- by default that is plain old .rst files02:22
xobsmithro: So it's not like perldoc / rustdoc / javadoc where it generates the documentation from the source files itself?02:23
mithroxobs: But Sphinx has a system for plugins which enable you to write less rst and pull data from other places, like Python docstrings02:23
mithroxobs: So Sphinx *can* work like perldoc / rustdoc / javadoc where it pulls data from your source files02:25
xobsmithro: thanks, that helps explain a lot about how Sphinx works.02:28
mithrosphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API "documentation tools."02:29
xobs"It was originally created for the Python documentation" -- I thought that meant it was pulled from pydoc02:29
mithroPeople have used sphinx just as a tool for generating documentation (In a similar vein to docbook / latex / etc) with rst files without any source code02:30
xobsOkay, sounds like a docbook replacement.  What is its relationship to "reStructured Text"?02:32
*** ademski has joined #tomu02:32
mithroReStructured Text (RST) is kind of like asciidoc / markdown / etc02:32
xobsmithro: Is there any canonical list of tags?  For example, "param", "returns", or "raises"?  Or is it entirely freeform?02:40
mithroxobs: For which part?03:01
mithroxobs: BTW It might be worth looking through the commits in https://github.com/xobs/valentyusb/pull/4 individually, so it shows how the sphinx initial quickstart was evolved in a pretty clear manner...03:02
tpbTitle: Adding sphinx docs to tri-fifo branch. by mithro · Pull Request #4 · xobs/valentyusb · GitHub (at github.com)03:02
mithroxobs: It's pretty freeform really...03:03
mithroxobs: sphinx has these things called "domains" -- they define expectations on around how documentation in that group is set up03:03
mithroA domain is a collection of markup (reStructuredText directives and roles) to describe and link to objects belonging together, e.g. elements of a programming language. Directive and role names in a domain have names like domain:name, e.g. py:function. Domains can also provide custom indices (like the Python Module Index).03:05
mithroxobs: The "Python Domain" defines the various expectations around things -- see https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-python-domain03:05
mithroxobs: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists03:06
xobsmithro: ah, thank you. "domains" was the keyword I was missing.03:07
mithroxobs: What napoleon sphinx extension does is take freeform text in either the "Google format" or the "NumPy format" and convert it into the RST tags03:07
xobsOkay, so "reStructured Text" isn't deprecated at all?03:08
*** rohitksingh has quit IRC03:09
mithroxobs: Well - With napoleon support now built into sphinx, you would be pretty stupid to use the restructured text method inside docstrings for your Python modules03:10
xobsI'm getting conflicting messages here...  How should I document valentyusb?03:11
mithroxobs: Did you understand what I mean by "docstrings" ?03:12
xobsmithro: I'm guessing you mean strings of documentation?03:12
mithroxobs: No - In python the work "docstring" has a very specific meaning03:12
mithroxobs: A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.03:13
mithrohttps://www.python.org/dev/peps/pep-0257/03:13
tpbTitle: PEP 257 -- Docstring Conventions | Python.org (at www.python.org)03:13
mithroxobs: https://github.com/xobs/valentyusb/pull/4#discussion_r32055290003:14
tpbTitle: Adding sphinx docs to tri-fifo branch. by mithro · Pull Request #4 · xobs/valentyusb · GitHub (at github.com)03:14
mithroxobs: IE This is a docstring --> https://github.com/xobs/valentyusb/blob/2c70a1256040b768e7649f641df0122ae2fb2fc2/valentyusb/usbcore/tx/nrzi.py#L12-L5203:15
tpbTitle: valentyusb/nrzi.py at 2c70a1256040b768e7649f641df0122ae2fb2fc2 · xobs/valentyusb · GitHub (at github.com)03:15
mithroIt will appear as the special attribute -- `TxNRZIEncoder.__doc__` -- which is what `help(TxNRZIEncoder)` will show....03:16
*** gio has quit IRC03:17
xobsOh, I see!  I didn't know that's what it was called, or that that's how it worked.03:17
mithroxobs: Understanding?03:17
xobsYes, that's somewhat surprising behavior.  But it's good to know that's how it works.03:18
mithroxobs: docstrings are a pretty fundamental part of Python which makes it trend to more usable :-) -- https://www.python.org/dev/peps/pep-0257/  -- "29-May-2001"03:19
tpbTitle: PEP 257 -- Docstring Conventions | Python.org (at www.python.org)03:19
mithroxobs: It's just a good idea that rust stole it :-) -> https://doc.rust-lang.org/rust-by-example/meta/doc.html#doc-comments03:23
xobsHmm... "pydoc3 docstring" and "pydoc3 docstrings" return no documentation, and "pydoc3 -k dostrings" just returns a module called `doctest`.03:23
xobsmithro: rust uses comments, not strings, which is what threw me off.03:24
*** gio has joined #tomu03:24
mithroxobs: Using strings rather than comments makes it easier on the Python introspection side of things03:25
xobsAlright.  I'll use docstrings from now on.03:25
mithroxobs: Couple of annoying things about docstrings03:26
mithroxobs: We never came up with a "proper" way of doing docstrings for attributes -- For example this attempt was rejected -> https://www.python.org/dev/peps/pep-0224/03:27
tpbTitle: PEP 224 -- Attribute Docstrings | Python.org (at www.python.org)03:27
mithroxobs: See https://stackoverflow.com/questions/3051241/how-to-document-class-attributes-in-python03:28
tpbTitle: How to document class attributes in Python? - Stack Overflow (at stackoverflow.com)03:28
mithroxobs: Python not having solved attribute doc strings is one of those "How is it 2019 and this still not solved" type problems in Python...03:29
xobsI see.  So in Python, when I say I want to document this register, what I'm really saying is that I want to "document an attribute"?03:31
*** ademski has quit IRC03:31
mithroxobs: In Python you normally document the attributes of a class in the classes doc string03:33
mithroxobs: IE This is what numpydoc suggests -> https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring03:33
tpbTitle: numpydoc docstring guide numpydoc v1.0.dev0 Manual (at numpydoc.readthedocs.io)03:33
mithroxobs: And the Google style -> https://github.com/google/styleguide/blob/gh-pages/pyguide.md#384-classes03:34
tpbTitle: styleguide/pyguide.md at gh-pages · google/styleguide · GitHub (at github.com)03:34
xobsThat seems to work fine for one-sentence descriptions of those attributes, but what about things like eptri, where the descriptions for each register are 15-20 lines?03:35
mithroxobs: The attribute description can be many lines long...03:35
mithroxobs: See this example -> https://github.com/xobs/valentyusb/blob/2c70a1256040b768e7649f641df0122ae2fb2fc2/valentyusb/usbcore/rx/bitstuff.py#L44-L4903:37
tpbTitle: valentyusb/bitstuff.py at 2c70a1256040b768e7649f641df0122ae2fb2fc2 · xobs/valentyusb · GitHub (at github.com)03:37
xobsAnd we could fit a wavedrom `reg_definition` there?03:37
mithroxobs: Yes - See https://github.com/mithro/valentyusb/blob/0dc9ba3ecba42461f3c0b63f948361c06fb22844/valentyusb/usbcore/cpu/eptri.py#L53-L10203:39
tpbTitle: valentyusb/eptri.py at 0dc9ba3ecba42461f3c0b63f948361c06fb22844 · mithro/valentyusb · GitHub (at github.com)03:39
xobsAlright, I'll try it.03:41
*** John_K has joined #tomu03:42
mithroxobs: See the output at https://mithro-valentyusb.readthedocs.io/en/latest/usbcore.cpu.html#module-usbcore.cpu.eptri03:42
tpbTitle: usbcore.cpu package ValentyUSB documentation (at mithro-valentyusb.readthedocs.io)03:42
xobsWhat does ".." and "::" mean in ".. wavedrom::"?  When do you use a single ":" and when do you use a double "::"?03:42
mithroxobs: That is restructure text directive...03:43
mithroxobs: https://www.sphinx-doc.org/en/2.0/usage/restructuredtext/basics.html#directives03:44
mithroxobs: restructured text directives are always `.. <directive>:: <arguments>`03:44
mithroxobs: No idea why they chose that form...03:45
xobsNot always.  Isn't `data : CSR` a directive?03:45
xobsOr is `:caption:` a directive?03:45
mithroNo `data : CSR` isn't a directive03:46
mithroxobs: napoleon converts that into `:param CSR data:` for rst to parse...03:48
mithroxobs: Actually, I think you might be right that `:<directive> <arguments>:` is a directive too...03:49
mithroxobs: Hrm, it might be that the format `:<option> <arguments>:` means it is an option to the current directive block you are inside?03:50
mithroxobs: See the `.. py:function::` example here -> https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists03:51
mithroI'm not expert on python documentation...03:51
xobsThe reStructured Text people seems to really like dots.03:52
mithroxobs: Side ways and horizontal it seems! :-)03:52
mithroxobs: Most of the time you don't need this level of detail...03:54
mithroxobs: You just write some nice docstrings and then use the default setup to get the API docs...03:55
xobsmithro: It's nice to know more about python documentation. I've always had a lot of trouble with it.03:58
mithroxobs: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html04:00
tpbTitle: Getting Started with Sphinx Read the Docs 3.7.3 documentation (at docs.readthedocs.io)04:00
xobsI merged the documentation stuff.  I'm still trying to get eptri working on real hardware (it works fine in simulation!), but I'll use this new method of documentation now.04:01
mithroxobs: If you feel strongly about having the documentation for the registers near the register instantiation, I can give you some options around that -- but it would be unique to this project and not something found in standard Python project...04:02
xobsIf that's how Python does it, then I'll do it that way as well.04:04
mithroxobs: FYI - If you want to get C/C++ documentation into the same place as the python documentation - you can use exhale - https://exhale.readthedocs.io/en/latest/ (which uses breathe - https://breathe.readthedocs.io/en/latest/) -- which allows you to import doxygen comments into sphinx...04:04
tpbTitle: Exhale Exhale: Automatic C++ Library API Generation (at exhale.readthedocs.io)04:04
xobsAt this point I'm trying to solve the problem of not having register-level documentation for system developers.04:06
xobsActually, that's still a thing that's missing -- what's the address of  these registers?04:06
xobsThat's a problem for the future, though.04:07
mithroxobs: I think maybe we have a sphinx tool which takes the .csv file and generates sphinx output?04:08
xobsFancy!04:09
mithroxobs: BUt that would need more docstrings to end up in the csv file -- so not sure if that is the right approach...04:34
mithroxobs: Can you go to https://readthedocs.org and set up an account?04:42
mithroxobs: Just trying to get valentyusb.readthedocs.io automatically publishing from your repo...04:46
xobsSure, one moment.04:48
mithroxobs: BTW Did you see that wavedrom-verilog thing I found? Lets you convert a wavedrom waveform into a Verilog file to drive a signal driver...04:52
xobsWeird.  Their confirmation email has a misleading address that my mail client flags as fishy.04:52
mithroxobs: Also -> https://github.com/wavedrom/datasheet04:58
tpbTitle: GitHub - wavedrom/datasheet: datasheet generator (at github.com)04:58
xobsmithro: still cleaning things up, but: https://github.com/xobs/valentyusb/blob/tri-fifo/valentyusb/usbcore/cpu/eptri.py#L5405:16
tpbTitle: valentyusb/eptri.py at tri-fifo · xobs/valentyusb · GitHub (at github.com)05:16
xobsThe tests pass now, and I think the documentation is in a format that should make sphinx happy.05:16
mithroxobs: Do you need instructions on how to run sphinx locally to check?05:17
xobs`Makefile:13: recipe for target 'help' failed`05:17
mithroShould just be `cd docs; make venv; make html` The `make venv` is only needed once or when the requirements change05:18
xobsIt looks like wavedrom isn't working.05:24
mithroxobs: I don't think wavedrom works from a local file05:35
mithroUse `python -m SimpleHTTPServer` and look at it that way?05:35
mithroOr make it render the images?05:36
xobsmithro: /usr/bin/python: No module named SimpleHTTPServer05:39
mithroI forget, it might be HTTPSimpleServer?05:42
mithrohttps://docs.python.org/2/library/simplehttpserver.html05:43
tpbTitle: 20.19. SimpleHTTPServer — Simple HTTP request handler Python 2.7.16 documentation (at docs.python.org)05:43
auscompgeekxobs: is your /usr/bin/python a python3?05:43
auscompgeekeither way `python3 -m http.server`05:44
xobsauscompgeek: Yes, I thought python2 was deprecated.05:44
xobsAh, that works.05:44
auscompgeekthe official recommendation to distros is to still have /usr/bin/python point to python205:44
auscompgeekhomebrew defaulted to python3 but then backflipped due to all the problems they had with that05:45
auscompgeekafaik only Arch still ignores that recommendation (which was written because of Arch in the first place)05:45
xobsJust my luck, I was using Arch.  Then I decided that, since Python 2 is dead, I'd remove it.05:46
mithroxobs: your very optimistic for someone who works with hardware05:51
mithroI did like that they might be removing the floppy disc driver from Linux :-P05:53
xobsmithro: So for one thing, it seems like vertical space matterns in reStructured Text.  There must be a blank line before the "::".05:54
xobsI fixed that, but now it's saying "invalid option block"05:54
mithroFull message output and input?05:55
xobsmithro: https://gist.github.com/xobs/4aa4213b2f17aabad620b16cebb2904605:55
tpbTitle: make html · GitHub (at gist.github.com)05:55
mithroMore new lines?05:56
auscompgeekI think you're missing a newline after the directives05:58
auscompgeeki.e. after `:caption:`05:59
mithroYeah, that was my guess too05:59
xobsAfter :caption:?05:59
mithroThis works -> https://github.com/mithro/valentyusb/blob/df5d9955b631ca85071c82e22c42384ef60290f6/valentyusb/usbcore/cpu/eptri.py#L6206:00
tpbTitle: valentyusb/eptri.py at df5d9955b631ca85071c82e22c42384ef60290f6 · mithro/valentyusb · GitHub (at github.com)06:00
xobsI put a blank line before :caption: and the error went away, but now I have no graphs.06:00
auscompgeekyou want a blank line between the :caption: line and the {06:00
auscompgeekno blank line between .. and :caption:06:01
xobsThat fixes it.06:02
mithroxobs: I would paste in an example you knew worked exactly (whitespace and all)06:03
mithroxobs: and *then* start modifying things06:03
xobsmithro: I started from your design, but I didn't think it worked that way.06:04
mithroI'm sure there is a logical reasoning why there need to be newlines - I don't know them...06:05
xobsMostly I didn't know what bits were grouped together, and having it spaced apart makes it very hard to follow.06:05
mithroOnce you are putting non-ascii stuff in your docstrings your optimising for the rendered output....06:06
*** craigo_ has quit IRC06:09
mithroThere is probably a sphinx extension to convert diagrams like TNT's at  https://github.com/smunaut/ice40-playground/blob/master/cores/usb/doc/mem-map.md06:12
tpbTitle: ice40-playground/mem-map.md at master · smunaut/ice40-playground · GitHub (at github.com)06:12
xobsNow to figure out how to make wavedrom generate registers that aren't quite so wide.06:13
mithroxobs: I only saw that issue locally not on the readthedocs website...06:21
mithrogot your readthedocs user set up so far?06:24
xobsmithro: yes, it's set up06:25
mithroUsername xobs?06:25
xobsCorrect06:25
mithrohttps://theamphour.com/456-3-discussing-fomu-with-tim-ansell-and-sean-cross/06:30
mithro1h 10m -- nice and short :-P06:33
xobsmithro: You're right, the registers on readthedocs.io aren't oversized, but for some reason it's expanded them to 32-bits.06:51
xobsOkay, the problem is that "readthedocs.io" renames the "config" json property to "options", so we need to put both values in there to get it to work.07:02
xobsI'm reasonably happy with this as a rough first-draft of some documentation: https://valentyusb.readthedocs.io/en/tri-fifo/usbcore.cpu.html#module-usbcore.cpu.eptri07:08
tpbTitle: usbcore.cpu package ValentyUSB documentation (at valentyusb.readthedocs.io)07:08
xobsHmm... I still don't know how I'm going to document individual register bits.07:38
*** alexhw_ has joined #tomu08:07
*** alexhw has quit IRC08:09
*** jljusten has quit IRC08:41
*** jljusten has joined #tomu08:45
xobsI also managed to get eptri about 90% done today. At least done enough that it sometimes enumerates on Linux.10:46
xobsThere's more work to do on resets, stalling out transactions, and some sequencing issues. But the design seems sound.10:47
*** LWK has joined #tomu11:11
*** yorick has quit IRC11:57
ovfxobs: great work!13:05
*** craigo_ has joined #tomu13:30
acathlaAnybody knows how to use a differential input on an iCE40 with migen?13:41
MadHackerInstantiate SB_IO (using Instance()) and set IO_STANDARD to SB_LVDS_INPUT, I think.13:45
xobsacathla: It'd be just like how we do the RGB LED in the workshop.13:46
acathlaHum, there is already a "class LatticeiCE40DifferentialInputImpl(Module):" in migen, in lattice/common.py, I wanted to use that but could not find a simple example.14:13
*** emeb has joined #tomu15:13
acathlaERROR: Bel 'X0/Y3/io1' of type 'SB_IO' is not valid for cell 'SB_IO' of type 'SB_IO' :(15:57
mithroacathla: Poke whitequark in #m-labs is probably productive15:57
*** rohitksingh has joined #tomu16:14
futarisIRCcloudxobs: How many endpoints does eptri have?17:02
*** rohitksingh has quit IRC17:37
*** rohitksingh has joined #tomu17:43
*** rohitksingh has quit IRC18:02
*** rohitksingh has joined #tomu18:18
*** rohitksingh has quit IRC18:24
*** guan has joined #tomu18:32
*** cedric has quit IRC18:37
*** cedric has joined #tomu18:38
*** cedric has joined #tomu18:38
futarisIRCcloudhttps://osfc.io/talks/hack-the-project-onboarding-process-learning-by-writing-tutorials-as-a-new-contributor18:47
tpbTitle: OSFC 2019 - Open Source Firmware Conference (at osfc.io)18:47
*** rohitksingh has joined #tomu19:34
mithrohttps://twitter.com/tardate/status/1169265772444540929?s=2019:43
*** Iker has joined #tomu19:57
IkerHi guys, I'm trying to update my Fomu's firmware with dfu-util -D evt-installable.dfu but I'm not able something is failing19:58
IkerAfter finishing, with no error, I cannot access it anymore and if I unplug and plug again I've my previous firmware version19:58
IkerThank you!19:58
*** cedric has quit IRC20:09
*** cedric has joined #tomu20:10
*** cedric has joined #tomu20:10
*** rohitksingh has quit IRC20:34
mithroIker: are you trying to update the bootloader?20:36
*** rohitksingh has joined #tomu20:38
IkerYes, I have 1.7.320:40
mithroIker: I don't know if there is an official process for updating the bootloader at the moment - you'll need to ask xobs20:48
IkerThank you Tim!20:49
IkerTo my understanding it shouldn't be done the way I have been doing20:49
IkerBut I saw on the slides that I could do that way20:49
mithroIker: which slides?20:49
IkerNot the slides sorry, the workshop walkthrough20:54
mithroIker: I'm pretty sure the workshop doesn't talk about updating the bootloader in any way?20:58
IkerI might misunderstood somethign21:02
IkerMy mistake, I have been reading so much docs, I was refering to this: https://fomu.im/td19/21:03
tpbTitle: Fomu at Teardown 2019 | I’m Fomu - an FPGA in your USB port (at fomu.im)21:03
Iker I've been through all the available docs so I mix what I have read in which21:08
*** rohitksingh has quit IRC21:11
*** rohitksingh has joined #tomu21:19
*** Iker has left #tomu21:24
*** Iker has joined #tomu21:25
*** Iker has quit IRC21:28
*** dzo has joined #tomu21:39
*** rohitksingh has quit IRC21:39
dzoHow to read buttons in Micropython?21:39
*** rohitksingh has joined #tomu22:06
*** dzo has quit IRC22:47
*** cdmatter has quit IRC22:58
*** emeb has quit IRC23:01
*** xkapastel has joined #tomu23:18
*** rohitksingh has quit IRC23:35

Generated by irclog2html.py 2.13.1 by Marius Gedminas - find it at mg.pov.lt!