| Time |
Nick |
Message |
| 01:05 |
|
mrcheese_ joined #luanti-docs |
| 05:00 |
|
MTDiscord joined #luanti-docs |
| 09:22 |
|
Warr1024 joined #luanti-docs |
| 09:47 |
|
Warr1024 joined #luanti-docs |
| 22:35 |
MTDiscord |
<mark.wiemer> https://github.com/luanti-org/docs.luanti.org/issues/296#issuecomment-3736141692, 🙂 TLDR: I still want Markdown, not MDX, because we can easily add MDX later. We need to write our own schema, checker, transformer, LSP server, and VS Code extension to get this work done. I've detailed a bit better what I mean with each of those terms in a new glossary section. |
| 22:36 |
|
mrcheese joined #luanti-docs |
| 23:14 |
MTDiscord |
<mark.wiemer> I think the true body of work is best described by new issue https://github.com/luanti-org/docs.luanti.org/issues/312, titled "Integrate Lua API information into IDEs", but I do want to keep the conversations focused on relevant sub-issues where valuable |
| 23:16 |
MTDiscord |
<mark.wiemer> Curious what you all feel would be necessary to close new issue https://github.com/luanti-org/docs.luanti.org/issues/315, titled "Agree on an approach for making docs parsable" |
| 23:31 |
MTDiscord |
<greenxenith> We dont need 2 issues for this |
| 23:32 |
MTDiscord |
<greenxenith> 315 is 100% a duplicate of 296 |
| 23:34 |
MTDiscord |
<greenxenith> This is also bikeshedding. We already agreed on markdown and a schema, and I have yet to see a practical clean implementation of such a schema |
| 23:35 |
MTDiscord |
<wsor4035> ok, so i looked at this link briefly, no schema, seems worthless |
| 23:36 |
MTDiscord |
<wsor4035> guess i should actually read it |
| 23:36 |
MTDiscord |
<wsor4035> ok yeah, no schema proposed in it |
| 23:36 |
MTDiscord |
<greenxenith> I like how its taken this much discussion to reach a conclusion we had already come to months ago. |
| 23:37 |
MTDiscord |
<wsor4035> also i dropped mdx forever ago in favor of using html in the markdown for the schema |
| 23:37 |
MTDiscord |
<wsor4035> mostly for compatibility and integration reasons |
| 23:37 |
MTDiscord |
<greenxenith> Yes, we want to use markdown or similar. Yes, we need to rewrite the whole docs. Yes, we need a parser/validator for the markdown. Yes, we need to be able to output to something an LSP can use. None of this is new. |
| 23:37 |
MTDiscord |
<wsor4035> also note my suggestion is more of a concept of a plan than a plan. |
| 23:38 |
MTDiscord |
<mark.wiemer> "markdown or similar" is not specific, is there anything blocking us from agreeing on "Markdown", period, no qualifier? |
| 23:39 |
MTDiscord |
<wsor4035> we already agreed on that ages ago |
| 23:39 |
MTDiscord |
<greenxenith> "markdown or similar" meaning I dont care |
| 23:39 |
MTDiscord |
<mark.wiemer> not new, but not written down |
| 23:39 |
MTDiscord |
<mark.wiemer> OK, I think I'll close https://github.com/luanti-org/docs.luanti.org/issues/315 saying we agree on using Markdown? |
| 23:39 |
MTDiscord |
<greenxenith> Yes, do it |
| 23:40 |
MTDiscord |
<wsor4035> having two issues for this seems pointless |
| 23:40 |
MTDiscord |
<wsor4035> https://cdn.discordapp.com/attachments/926231483155378176/1460055700746145926/image.png?ex=69658655&is=696434d5&hm=5e39db3e9d3a1a3ea67a30debf8bd9ffb9671985a08eeea14c86c7a407365af2& |
| 23:40 |
MTDiscord |
<mark.wiemer> did you read the descriptions? |
| 23:40 |
MTDiscord |
<wsor4035> but idrc |
| 23:40 |
MTDiscord |
<wsor4035> yes |
| 23:41 |
MTDiscord |
<wsor4035> ok, i expand it to all of these. given we should only care about ides that support lsp, but 🤷 |
| 23:41 |
MTDiscord |
<wsor4035> https://cdn.discordapp.com/attachments/926231483155378176/1460055989444415576/image.png?ex=6965869a&is=6964351a&hm=57b212484648a902b1196960ec13ec60efa6fbe7a52ca8250616a4f08c200e87& |
| 23:41 |
MTDiscord |
<mark.wiemer> OK. I'll quickly comment that I feel like I"m getting a lot of flak for a good faith effort that does document things that weren't previously documented in GitHub 🙁 |
| 23:41 |
MTDiscord |
<greenxenith> Im only giving you flak for the duplicate, I think the others are fine |
| 23:41 |
MTDiscord |
<mark.wiemer> I'm not sure what you mean. You expand your belief that it seems pointless? I just don't think that's constructive |
| 23:42 |
MTDiscord |
<mark.wiemer> this comes off as "flak" to me for the record. Just doesn't seem constructive, if anything, it's discouraging 🙁 |
| 23:42 |
MTDiscord |
<greenxenith> Alright, fair |
| 23:42 |
MTDiscord |
<greenxenith> I am heavily against bikeshedding, and this feels like bikeshedding to me, which is also not constructive |
| 23:42 |
MTDiscord |
<wsor4035> vscode extension is going to be 99% the same as any other ide as lsp is a thing. its just packaging and submitting, not sure that the two issues are justified, but idrc |
| 23:43 |
MTDiscord |
<greenxenith> From our point of view, you were already working on a markdown schema solution, and now we are going back to this for some reason. |
| 23:43 |
MTDiscord |
<mark.wiemer> I strongly disagree that this is bikeshedding. Up until 2 weeks ago I was strongly considering LuaCATS or TypeScript, would've been a radically different path |
| 23:43 |
MTDiscord |
<wsor4035> lets move on from having a bunch of issues unless someone else cares. |
| 23:43 |
MTDiscord |
<mark.wiemer> I tried to clarify with the title of "make docs programmatically parsable" that the goal was not approach-specific, e.g. it could've been LuaCATS, Markdown, other. |
| 23:44 |
MTDiscord |
<mark.wiemer> I want to have many small issues to clearly break down what is effectively a huge body of work |
| 23:44 |
MTDiscord |
<greenxenith> At some point breaking down issues too far just makes needlessly little issues. There is a saying for this I dont remember. |
| 23:44 |
MTDiscord |
<wsor4035> personally i think its boreding on over management, but as you are a team member, i trust you and defer to your "expertise" because i dont care enough |
| 23:44 |
MTDiscord |
<greenxenith> But I dont mind breaking the problem down, I see value in the other issues |
| 23:45 |
MTDiscord |
<mark.wiemer> I did say I'd be working on a checker/transformer POC but I ended last convo with "why not use MDX, I don't care, just saying" but that convo lasted a long time so I felt it worth documenting |
| 23:45 |
MTDiscord |
<greenxenith> I believe I am also put off because I didn't see any other team members heavily backing things outside of markdown |
| 23:46 |
MTDiscord |
<wsor4035> anyways, if i understand the current pile of issues, we should be focusing on https://github.com/luanti-org/docs.luanti.org/issues/297 now and getting people to solicit proposals for what such a schema should look like? |
| 23:46 |
MTDiscord |
<mark.wiemer> and then I created the GH issues to give myself a good feel for the different pieces of work we need. I don't think it'll be a trivial bit of work to turn LSP data into VS Code extension. As someone who wrote hello world in LSP VS Code extension and maintains another LSP VS Code extension, there is a lot nuance. It's not a few clicks or lines of code by any means |
| 23:46 |
MTDiscord |
<greenxenith> The VSCode extension is not our concern right now, at least |
| 23:46 |
MTDiscord |
<mark.wiemer> yes, next step is to get what a proposal should look like. we already have the riseup pad, a gist, and other docs to reference. I'll be going through those in detail next and making my own proposal |
| 23:47 |
MTDiscord |
<mark.wiemer> correct, but it is on the backlog as it is something I want us to take up eventually. Hence the issue creation |
| 23:47 |
MTDiscord |
<greenxenith> Which I am fine with |
| 23:47 |
MTDiscord |
<mark.wiemer> OK, I'm off to a thing, see you guys in several hours or tomorrow or next weekend 😄 |
| 23:47 |
MTDiscord |
<wsor4035> can you only pin two issues on github? |
| 23:47 |
MTDiscord |
<mark.wiemer> 3 I think |
| 23:47 |
MTDiscord |
<greenxenith> I swear ive seen 3 |
| 23:47 |
MTDiscord |
<wsor4035> same |
| 23:47 |
MTDiscord |
<wsor4035> trying to figure out pinning an issue |
| 23:47 |
MTDiscord |
<wsor4035> having a dumb moment |
| 23:48 |
MTDiscord |
<wsor4035> found it |
| 23:48 |
MTDiscord |
<wsor4035> pinned #297 as its the current focus/priority |
| 23:48 |
MTDiscord |
<wsor4035> @ExeVirus would you be so kind as to comment your proposed markdown schema in https://github.com/luanti-org/docs.luanti.org/issues/297 |
| 23:52 |
MTDiscord |
<a.corp.serot> i will comment mine too |
| 23:53 |
MTDiscord |
<greenxenith> For schemas: * We should identify what type if information is critical for using the API, what information is useful, and what is optional * The format does not have to be perfected since a consistent schema will allow us to change it at any time fairly trivially * Examples, examples, examples |
| 23:55 |
MTDiscord |
<a.corp.serot> done, i prefer the markdown-custom style less after trying out the XML style. |
| 23:55 |
MTDiscord |
<wsor4035> i hide a bunch of the existing stuff, since it was all rather offtopic |
| 23:56 |
MTDiscord |
<a.corp.serot> but ofc, i'm not part of the docs team so the choices are up to you guys |
| 23:56 |
MTDiscord |
<wsor4035> would you mind putting a quick code sample in your comment? |
| 23:56 |
MTDiscord |
<a.corp.serot> ok |
| 23:57 |
MTDiscord |
<greenxenith> I have to imagine some sort of YAML-like would be much more concise while retaining the XML type of sctructure |
| 23:59 |
MTDiscord |
<a.corp.serot> i argued in the riseup docs the same thing. my <!-- --> comments are still visible if you see the raw text |
| 23:59 |
MTDiscord |
<a.corp.serot> sorry, not the same thing, rather that it could be YAML or any similar language |
