15:27 <mithro> xobs: FYI You might want to look at testwrap.dedent for having triple quoted strings in Python be aligned with surrounding code

15:28 <mithro> xobs: https://pymotw.com/2/textwrap/

15:28 <tpb> Title: textwrap Formatting text paragraphs - Python Module of the Week (at pymotw.com)

15:28 <mithro> https://github.com/amontalenti/elements-of-python-style/issues/26

15:28 <tpb> Title: Suggest using `textwrap.dedent()` to keep indentation even with triple-quote multi-line strings · Issue #26 · amontalenti/elements-of-python-style · GitHub (at github.com)

15:28 <mithro> https://docs.python.org/3.1/library/textwrap.html

15:28 <tpb> Title: 7.5. textwrap — Text wrapping and filling Python v3.1.5 documentation (at docs.python.org)

15:30 <xobs> mithro: Thanks, that looks super useful for this sort of thing. I wonder why it's not more widely known

15:30 <xobs> I'll have to look into using that myself. I saw someone used regular expressions on Stack Overflow to accomplish that, which is as far as I'd gotten.

15:31 <xobs> xobs: Any recommendations on how we can extract various sections out of a docstring? Or how we could use sphinx? Right now I generate rst files after `soc.do_exit(vns)` and just run sphinx on that.

15:32 <mithro> xobs: I only found about it a year or two ago and I've been programming in Python since 1998

15:32 <xobs> If there were a way to parse out the various Module docstrings, that would be very useful.

15:32 <mithro> xobs: I would suggest using rst headers / section thingies

15:34 <xobs> sphinx is, ironically, not well documented. For example, in lxsocdoc, I make each register a `subsubsection`, but in the resulting html it makes them `<h1>` "section"s. I haven't figured out how to not have it include subsubsections all over the place. Or how to include sections.

15:37 <xobs> Is docutils part of python, or is it something that got pulled in by sphinx?

15:45 <xobs> I see. No, it's not part of the standard distribution, but it has no dependencies and no build requirements other than 3.5+ (same as litex)

16:28 <xobs> This came up over in #fomu, but is there any particular reason why `CSRStatus` fields have no `.we` signal?

16:52 <mithro> xobs: FYI I would recommend using rst headers / blocks. You can then use docutils to easily extract the sections.

16:53 <mithro> xobs: https://www.sphinx-doc.org/en/master/_modules/docutils/parsers/rst.html

16:54 <xobs> mithro: I really don't want to depend on a module like that.

16:54 <mithro> xobs: Why not? docutils is a standard library module?

16:55 <xobs> It doesn't look like it's part of the standard library. At least it's not listed at https://docs.python.org/3/library/index.html

16:55 <tpb> Title: The Python Standard Library Python 3.7.4 documentation (at docs.python.org)

16:55 <mithro> Oh maybe I'm wrong...

16:55 <xobs> The best way seems to be to generate files that can then be fed into sphinx.

16:56 <xobs> I just spent the afternoon helping Bunnie fix his system that has a conflicting sphinx setup. So the fewer modules we need the better.

16:56 <mithro> https://docs.python.org/3/library/inspect.html#inspect.getcomments

16:56 <tpb> Title: inspect — Inspect live objects Python 3.7.4 documentation (at docs.python.org)

16:56 <mithro> xobs: This is why you use self contained Python environments

16:57 <xobs> Also, docutils seems to require python 3.5+. litex requires python 3.5+, but I'm afraid of them changing things.

16:59 <mithro> 0.15 is the last to support Python 2.6, 3.3, and 3.4.

16:59 <mithro> Docutils is compatible with Python versions 2.7, and 3.5 to 3.7

17:01 <xobs> Right, but my concern is that they don't seem to care much for backwards-compatibility. And I don't see the benefit of doing it that way versus having a sentinal. The drawbacks are needing to package another module, and depending on something that has shown that they will drop support for older versions. What are the benefits?

17:03 <mithro> xobs: The choice is "do something custom which will continue to grow in complexity until it reaches the same as the existing solutions" or "Use the current existing most popular solution which has been around a long time and is the default option Python people would reach for (and has a lot of stackoverflow and other existing solutions)"

17:06 <mithro> xobs: FYI - The longer you wait to upgrade things, the more painful the upgrade is going to be

17:12 <xobs> mithro: It'll need to be nonstandard anyway. The choice is whether we have a nonstandard prefix on the header, or we have a special sentinal.

17:13 <mithro> xobs: Extend an existing standard is better than inventing a new one...

17:13 <xobs> I really don't like to add python packages. They always seem to break. The wavedrom sphinx plugin, for example, fails to install because it requires libxcb.dll

17:15 <xobs> The idea came from perlpod, which is an existing standard.

17:30 <mithro> xobs: btw - https://github.com/enjoy-digital/litex/pull/253#issuecomment-533138458

17:30 <tpb> Title: WIP: Enable link-time-optimization on LiteX builds by mithro · Pull Request #253 · enjoy-digital/litex · GitHub (at github.com)

17:31 <mithro> xobs: You can probably just use your regex / string approach and make the sentinel a rst block compatible? https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst#blocks

17:31 <tpb> Title: rst-cheatsheet/rst-cheatsheet.rst at master · ralsina/rst-cheatsheet · GitHub (at github.com)

17:46 <mithro> xobs: My suggestion -> https://github.com/enjoy-digital/litex/pull/259#issuecomment-533648773

17:46 <tpb> Title: timer: add documentation by xobs · Pull Request #259 · enjoy-digital/litex · GitHub (at github.com)

19:55 <mithro> xobs: with that syntax, it is pretty trivial to write a sphinx extension which takes all those sections and pulls it together.