| 11 Aug 2023 |
 alejandrosame | infinisil: I'm already part of NixOS/nixpkgs-maintainers -> https://discourse.nixos.org/t/join-the-package-maintainer-team/3751/68?u=alejandrosame | 08:38:03 |
 asymmetric | In reply to @osslate:fsfe.org
I liken it to: imagine a program written in something like Nix or C. Now, imagine instead of one statement per line, the entire program was smushed together, with newlines only occurring at the 80 col mark.
...now, imagine receiving a substantial PR to change something in that spaghetti :D Iām not saying new lines should only be at the 80 column mark, people are free to break after each sentence according to semantics, presentation, etc | 09:09:56 |
| asymmetric | But the 80 column mark provides an upper bound for sentence length | 09:10:24 |
 osslate | In reply to @asymmetric:matrix.dapp.org.uk
But the 80 column mark provides an upper bound for sentence length How do you determine the "correct" upper bound for sentence length? | 09:14:20 |
| osslate | Documentation isn't poetry š
editing is very intuition based (beyond style guides which cover grammar, voice, correct spelling/case for terms) | 09:16:47 |
| osslate | Also considering that a defined column length will be inclusive of markup (code segments, bold, italic, etc.) which isn't ideal either | 09:19:15 |
| osslate | Contradicting myself here after saying "documentation isn't poetry", but a real metric that can be used is word count in an individual sentence. Column wrapping isn't useful to get that metric, though | 09:24:31 |
 infinisil | I've been using the one-sentence-per-line convention for some time now, and I'm a big fan of it. | 09:48:37 |
| infinisil | Or, I've become a big fan of it, makes reviews easier and diffs nicer | 09:52:16 |
| infinisil | And hints at sentences that could be broken up | 09:52:41 |
 @brian:bmcgee.ie | Have to admit I like semantic line breaks. First time seeing it, but my eyeballs immediately went "yeah, we like that" | 11:31:11 |
 @mightyiam:matrix.org | I can use some help with this pty-in-build-phase problem:
https://github.com/NixOS/nix.dev/pull/672#issuecomment-1674627870 | 12:08:53 |
| 12 Aug 2023 |
 Jan Tojnar | zmitchell: did you ever start looking into https://github.com/nix-community/nixdoc/issues/19? | 08:28:57 |
| 13 Aug 2023 |
|  @10leej:matrix.org joined the room. | 01:27:06 |
| 14 Aug 2023 |
| infinisil | I spent a lot of time on https://github.com/NixOS/nixpkgs/pull/245243, it's a beast, but it would be great to get some rough review on it and then merge it. It's not perfect, but it makes a lot of improvements. | 03:18:56 |
| asymmetric | Just found out about outreachy: https://www.outreachy.org/
Guix has been one of the projects interns could work on: https://www.outreachy.org/communities/cfp/gnu-guix/
Maybe we could look into this? | 08:06:53 |
| @mightyiam:matrix.org | Yuki (they/them): help me with sphinx, I'm drowning | 15:18:50 |
| @mightyiam:matrix.org | I'm trying to make an extension that replaces the nix-repl language tag with the text language tag. By language tag I mean the first word after the triple backtick in fenced code blocks.
from docutils import nodes
from docutils.parsers.rst import directives
from sphinx.util.docutils import SphinxDirective
class Directive(SphinxDirective):
has_content = True
def run(self):
content = '\n'.join(self.content)
code_block = nodes.literal_block(classes=['nix-repl'], language='text')
code_block.append(nodes.Text(content))
return [code_block]
def setup(app):
app.add_directive('nix-repl', Directive)
| 15:20:59 |
| @mightyiam:matrix.org | That stuff doesn't seem to do what I want, though. We still get a warning that there is no such language as nix-repl. | 15:21:42 |
 Yuki Langley (they/them) | Why do you want to do this? | 15:23:18 |
| Yuki Langley (they/them) | Is the goal to extract all code that has "nix-repl" | 15:23:47 |
| Yuki Langley (they/them) | * Is the goal to extract all code that has "nix-repl"? | 15:23:48 |
| osslate | If recognizing/extracting repl codeblocks is the goal, it might be better to engineer a solution that enumerates over nix (or text) codeblocks and identifies the nix repl prompt | 15:24:42 |
| @mightyiam:matrix.org | Because I really want to mark some fenced code blocks as nix-repl.
I wrote a program that parses the same sources, unrelated to sphinx, runs those nix repl examples in actual nix repl.
| 15:24:52 |
| @mightyiam:matrix.org | Identifying the prompt sounds like a workaround that affects the author of the documentation. | 15:26:22 |
| @mightyiam:matrix.org | The author of the documentation "wants", according to me, to have nix-repl as the language tag. | 15:26:45 |
| @mightyiam:matrix.org | All the silly extension has to do, is to replace all nix-repl language tags with text. | 15:27:20 |
| osslate | Is this a thing that people have asked for previously? | 15:27:35 |
| Yuki Langley (they/them) | sphinx.ext.doctest is an extension which does something similar: https://github.com/sphinx-doc/sphinx/blob/0bad447070d45fc5538aed9bf15a1716c628f321/sphinx/ext/doctest.py#L157
https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html#module-sphinx.ext.doctest
| 15:27:50 |
| Yuki Langley (they/them) | * sphinx.ext.doctest is an extension which does something similar (but for Python): https://github.com/sphinx-doc/sphinx/blob/0bad447070d45fc5538aed9bf15a1716c628f321/sphinx/ext/doctest.py#L157
https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html#module-sphinx.ext.doctest
| 15:28:00 |
