This is for the sake of the new rST generator (the "transmogrifier") so
we can advance multiple lines on occasion while keeping the
generated<-->source mappings accurate.
next_line now simply takes an optional n parameter which chooses the
number of lines to advance.
RFC: Here's the exorbitant detail on why I want this:
This is used mainly when converting section syntax in free-form
documentation to more traditional rST section header syntax, which
does not always line up 1:1 for line counts.
For example:
```
##
# = Section <-- Info is pointing here, "L1"
#
# Lorem Ipsum
##
```
would be transformed to rST as:
```
======= <-- L1
Section <-- L1
======= <-- L1
<-- L2
Lorem Ipsum <-- L3
```
After consuming the single "Section" line from the source, we want to
advance the source pointer to the next non-empty line which requires
jumping by more than one line.
Signed-off-by: John Snow <jsnow@redhat.com>
---
scripts/qapi/source.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/scripts/qapi/source.py b/scripts/qapi/source.py
index 7b379fdc925..ffdc3f482ac 100644
--- a/scripts/qapi/source.py
+++ b/scripts/qapi/source.py
@@ -47,9 +47,9 @@ def set_defn(self, meta: str, name: str) -> None:
self.defn_meta = meta
self.defn_name = name
- def next_line(self: T) -> T:
+ def next_line(self: T, n: int = 1) -> T:
info = copy.copy(self)
- info.line += 1
+ info.line += n
return info
def loc(self) -> str:
--
2.47.0John Snow <jsnow@redhat.com> writes: > This is for the sake of the new rST generator (the "transmogrifier") so > we can advance multiple lines on occasion while keeping the > generated<-->source mappings accurate. > > next_line now simply takes an optional n parameter which chooses the > number of lines to advance. > > > RFC: Here's the exorbitant detail on why I want this: > > This is used mainly when converting section syntax in free-form > documentation to more traditional rST section header syntax, which > does not always line up 1:1 for line counts. > > For example: > > ``` > ## > # = Section <-- Info is pointing here, "L1" > # > # Lorem Ipsum > ## > ``` > > would be transformed to rST as: > > ``` > ======= <-- L1 > Section <-- L1 > ======= <-- L1 > <-- L2 > Lorem Ipsum <-- L3 > ``` I can't help to wonder... Could we simply use rST markup instead? "Later", "maybe later", or even "please ask me later" would be perfectly acceptable answers. > After consuming the single "Section" line from the source, we want to > advance the source pointer to the next non-empty line which requires > jumping by more than one line. > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > scripts/qapi/source.py | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git a/scripts/qapi/source.py b/scripts/qapi/source.py > index 7b379fdc925..ffdc3f482ac 100644 > --- a/scripts/qapi/source.py > +++ b/scripts/qapi/source.py > @@ -47,9 +47,9 @@ def set_defn(self, meta: str, name: str) -> None: > self.defn_meta = meta > self.defn_name = name > > - def next_line(self: T) -> T: > + def next_line(self: T, n: int = 1) -> T: > info = copy.copy(self) > - info.line += 1 > + info.line += n > return info > > def loc(self) -> str: Assuming we need this: Reviewed-by: Markus Armbruster <armbru@redhat.com>
On Fri, Dec 20, 2024 at 8:22 AM Markus Armbruster <armbru@redhat.com> wrote: > John Snow <jsnow@redhat.com> writes: > > > This is for the sake of the new rST generator (the "transmogrifier") so > > we can advance multiple lines on occasion while keeping the > > generated<-->source mappings accurate. > > > > next_line now simply takes an optional n parameter which chooses the > > number of lines to advance. > > > > > > RFC: Here's the exorbitant detail on why I want this: > > > > This is used mainly when converting section syntax in free-form > > documentation to more traditional rST section header syntax, which > > does not always line up 1:1 for line counts. > > > > For example: > > > > ``` > > ## > > # = Section <-- Info is pointing here, "L1" > > # > > # Lorem Ipsum > > ## > > ``` > > > > would be transformed to rST as: > > > > ``` > > ======= <-- L1 > > Section <-- L1 > > ======= <-- L1 > > <-- L2 > > Lorem Ipsum <-- L3 > > ``` > > I can't help to wonder... Could we simply use rST markup instead? > > "Later", "maybe later", or even "please ask me later" would be perfectly > acceptable answers. > Yeah, I'd be happy with that, I just didn't want to add more complexity to the pile so I went for what I felt was "simplest": - Leave source syntax alone - Copy and modify the existing freeform doc parser - Quickly allow for multi-line advancing where it appeared to be important. Modifying freeform syntax to be purely rST that isn't modified or rewritten at all has benefits: - No need to mangle or multiplex source line source information - Less code - More straightforward I'm quite happy to do it later, is there some kind of "ticket" system you'd tolerate using for tracking nits for cleanup? I *will* forget if we don't listify and track them, I'm sorry (but wise enough) to admit. I just don't want to get sidetracked on little side-quests right now. (Quite prone to this...) > > > After consuming the single "Section" line from the source, we want to > > advance the source pointer to the next non-empty line which requires > > jumping by more than one line. > > > > Signed-off-by: John Snow <jsnow@redhat.com> > > --- > > scripts/qapi/source.py | 4 ++-- > > 1 file changed, 2 insertions(+), 2 deletions(-) > > > > diff --git a/scripts/qapi/source.py b/scripts/qapi/source.py > > index 7b379fdc925..ffdc3f482ac 100644 > > --- a/scripts/qapi/source.py > > +++ b/scripts/qapi/source.py > > @@ -47,9 +47,9 @@ def set_defn(self, meta: str, name: str) -> None: > > self.defn_meta = meta > > self.defn_name = name > > > > - def next_line(self: T) -> T: > > + def next_line(self: T, n: int = 1) -> T: > > info = copy.copy(self) > > - info.line += 1 > > + info.line += n > > return info > > > > def loc(self) -> str: > > Assuming we need this: > Reviewed-by: Markus Armbruster <armbru@redhat.com> Thanks! We can always drop stuff later if we wind up not needing it, it's just a means to an end. --js
John Snow <jsnow@redhat.com> writes: > On Fri, Dec 20, 2024 at 8:22 AM Markus Armbruster <armbru@redhat.com> wrote: > >> John Snow <jsnow@redhat.com> writes: >> >> > This is for the sake of the new rST generator (the "transmogrifier") so >> > we can advance multiple lines on occasion while keeping the >> > generated<-->source mappings accurate. >> > >> > next_line now simply takes an optional n parameter which chooses the >> > number of lines to advance. >> > >> > >> > RFC: Here's the exorbitant detail on why I want this: >> > >> > This is used mainly when converting section syntax in free-form >> > documentation to more traditional rST section header syntax, which >> > does not always line up 1:1 for line counts. >> > >> > For example: >> > >> > ``` >> > ## >> > # = Section <-- Info is pointing here, "L1" >> > # >> > # Lorem Ipsum >> > ## >> > ``` >> > >> > would be transformed to rST as: >> > >> > ``` >> > ======= <-- L1 >> > Section <-- L1 >> > ======= <-- L1 >> > <-- L2 >> > Lorem Ipsum <-- L3 >> > ``` >> >> I can't help to wonder... Could we simply use rST markup instead? >> >> "Later", "maybe later", or even "please ask me later" would be perfectly >> acceptable answers. >> > > Yeah, I'd be happy with that, I just didn't want to add more complexity to > the pile so I went for what I felt was "simplest": Avoiding mission creep is good. > - Leave source syntax alone > - Copy and modify the existing freeform doc parser > - Quickly allow for multi-line advancing where it appeared to be important. > > Modifying freeform syntax to be purely rST that isn't modified or rewritten > at all has benefits: > > - No need to mangle or multiplex source line source information > - Less code > - More straightforward > > I'm quite happy to do it later, is there some kind of "ticket" system you'd > tolerate using for tracking nits for cleanup? I *will* forget if we don't > listify and track them, I'm sorry (but wise enough) to admit. I just don't > want to get sidetracked on little side-quests right now. (Quite prone to > this...) TODO comment in code this would obviously kill? Not exactly a ticket system... scripts/qapi/TODO? Still not a ticket system... Other ideas? >> > After consuming the single "Section" line from the source, we want to >> > advance the source pointer to the next non-empty line which requires >> > jumping by more than one line. >> > >> > Signed-off-by: John Snow <jsnow@redhat.com> >> > --- >> > scripts/qapi/source.py | 4 ++-- >> > 1 file changed, 2 insertions(+), 2 deletions(-) >> > >> > diff --git a/scripts/qapi/source.py b/scripts/qapi/source.py >> > index 7b379fdc925..ffdc3f482ac 100644 >> > --- a/scripts/qapi/source.py >> > +++ b/scripts/qapi/source.py >> > @@ -47,9 +47,9 @@ def set_defn(self, meta: str, name: str) -> None: >> > self.defn_meta = meta >> > self.defn_name = name >> > >> > - def next_line(self: T) -> T: >> > + def next_line(self: T, n: int = 1) -> T: >> > info = copy.copy(self) >> > - info.line += 1 >> > + info.line += n >> > return info >> > >> > def loc(self) -> str: >> >> Assuming we need this: >> Reviewed-by: Markus Armbruster <armbru@redhat.com> > > Thanks! We can always drop stuff later if we wind up not needing it, it's > just a means to an end. Yes, and this one isn't exactly a complexity bomb :)
On Thu, Jan 9, 2025, 3:00 AM Markus Armbruster <armbru@redhat.com> wrote: > John Snow <jsnow@redhat.com> writes: > > > On Fri, Dec 20, 2024 at 8:22 AM Markus Armbruster <armbru@redhat.com> > wrote: > > > >> John Snow <jsnow@redhat.com> writes: > >> > >> > This is for the sake of the new rST generator (the "transmogrifier") > so > >> > we can advance multiple lines on occasion while keeping the > >> > generated<-->source mappings accurate. > >> > > >> > next_line now simply takes an optional n parameter which chooses the > >> > number of lines to advance. > >> > > >> > > >> > RFC: Here's the exorbitant detail on why I want this: > >> > > >> > This is used mainly when converting section syntax in free-form > >> > documentation to more traditional rST section header syntax, which > >> > does not always line up 1:1 for line counts. > >> > > >> > For example: > >> > > >> > ``` > >> > ## > >> > # = Section <-- Info is pointing here, "L1" > >> > # > >> > # Lorem Ipsum > >> > ## > >> > ``` > >> > > >> > would be transformed to rST as: > >> > > >> > ``` > >> > ======= <-- L1 > >> > Section <-- L1 > >> > ======= <-- L1 > >> > <-- L2 > >> > Lorem Ipsum <-- L3 > >> > ``` > >> > >> I can't help to wonder... Could we simply use rST markup instead? > >> > >> "Later", "maybe later", or even "please ask me later" would be perfectly > >> acceptable answers. > >> > > > > Yeah, I'd be happy with that, I just didn't want to add more complexity > to > > the pile so I went for what I felt was "simplest": > > Avoiding mission creep is good. > > > - Leave source syntax alone > > - Copy and modify the existing freeform doc parser > > - Quickly allow for multi-line advancing where it appeared to be > important. > > > > Modifying freeform syntax to be purely rST that isn't modified or > rewritten > > at all has benefits: > > > > - No need to mangle or multiplex source line source information > > - Less code > > - More straightforward > > > > I'm quite happy to do it later, is there some kind of "ticket" system > you'd > > tolerate using for tracking nits for cleanup? I *will* forget if we don't > > listify and track them, I'm sorry (but wise enough) to admit. I just > don't > > want to get sidetracked on little side-quests right now. (Quite prone to > > this...) > > TODO comment in code this would obviously kill? Not exactly a ticket > system... > > scripts/qapi/TODO? Still not a ticket system... > If a TODO is fine (and you don't mind pinging me in the future), then the comment I left in the visit_freeform() function (it's in another patch) explaining that the custom parser can be dropped after we sunset the old qapidoc is likely sufficient if I just add a "TODO". Sound good? > Other ideas? > > >> > After consuming the single "Section" line from the source, we want to > >> > advance the source pointer to the next non-empty line which requires > >> > jumping by more than one line. > >> > > >> > Signed-off-by: John Snow <jsnow@redhat.com> > >> > --- > >> > scripts/qapi/source.py | 4 ++-- > >> > 1 file changed, 2 insertions(+), 2 deletions(-) > >> > > >> > diff --git a/scripts/qapi/source.py b/scripts/qapi/source.py > >> > index 7b379fdc925..ffdc3f482ac 100644 > >> > --- a/scripts/qapi/source.py > >> > +++ b/scripts/qapi/source.py > >> > @@ -47,9 +47,9 @@ def set_defn(self, meta: str, name: str) -> None: > >> > self.defn_meta = meta > >> > self.defn_name = name > >> > > >> > - def next_line(self: T) -> T: > >> > + def next_line(self: T, n: int = 1) -> T: > >> > info = copy.copy(self) > >> > - info.line += 1 > >> > + info.line += n > >> > return info > >> > > >> > def loc(self) -> str: > >> > >> Assuming we need this: > >> Reviewed-by: Markus Armbruster <armbru@redhat.com> > > > > Thanks! We can always drop stuff later if we wind up not needing it, it's > > just a means to an end. > > Yes, and this one isn't exactly a complexity bomb :) >
John Snow <jsnow@redhat.com> writes: > On Thu, Jan 9, 2025, 3:00 AM Markus Armbruster <armbru@redhat.com> wrote: > >> John Snow <jsnow@redhat.com> writes: [...] >> > Modifying freeform syntax to be purely rST that isn't modified or rewritten >> > at all has benefits: >> > >> > - No need to mangle or multiplex source line source information >> > - Less code >> > - More straightforward >> > >> > I'm quite happy to do it later, is there some kind of "ticket" system you'd >> > tolerate using for tracking nits for cleanup? I *will* forget if we don't >> > listify and track them, I'm sorry (but wise enough) to admit. I just don't >> > want to get sidetracked on little side-quests right now. (Quite prone to >> > this...) >> >> TODO comment in code this would obviously kill? Not exactly a ticket >> system... >> >> scripts/qapi/TODO? Still not a ticket system... >> > > If a TODO is fine (and you don't mind pinging me in the future), then the > comment I left in the visit_freeform() function (it's in another patch) > explaining that the custom parser can be dropped after we sunset the old > qapidoc is likely sufficient if I just add a "TODO". > > Sound good? Yes. [...]
© 2016 - 2025 Red Hat, Inc.