yvanzo: where does the code for *those* docs live? If you know
2022-01-18 01810, 2022
alastairp
lucifer: not sure. how about we focus on LB for now, get the docs ready, and then see how generic they are? - which should give us some guideline on where we could put them
2022-01-18 01847, 2022
yvanzo
reosarevok: I don’t
2022-01-18 01841, 2022
lucifer
alastairp: sounds good. đź‘Ť
2022-01-18 01851, 2022
alastairp
lucifer: to me I think it's pretty clear that there's a good place for the click docs in the LB Developers section, and #1650 in the Maintainers section. what do you think
2022-01-18 01822, 2022
lucifer
+1, that's how its organized currenlty.
2022-01-18 01848, 2022
lucifer
i am thinking of a section on dumps in maintainers section too dealing with dump issues on prod.
2022-01-18 01816, 2022
alastairp
sounds good
2022-01-18 01808, 2022
alastairp
I'm just building #1823, to see if I have some further suggestions for naming and introduction text
2022-01-18 01811, 2022
monkey
For reference about the BB API docs, we're using swagger and the docs are in the API code files themselves.
2022-01-18 01811, 2022
monkey
Then when serving the API another module is started which reads Swagger docs and serves html pages accordingly.
Inlining the docs with the code in particular I find is very helpful. Fewer opportunities to forget to update the docs, and easier to compare code and docs to ensure correctness
2022-01-18 01805, 2022
alastairp
we more or less have the same thing in LB with a different tool, but its interface isn't as cool as swagger
2022-01-18 01825, 2022
monkey
Right
2022-01-18 01848, 2022
monkey
Maybe there is an equivalent tool that serves the docs? Could also be done on github pages for example
2022-01-18 01820, 2022
alastairp
eh - actually. looking at the BB swagger again, the only thing that LB is missing is the "Try it out" button. everything else is just a matter of correctly documenting each value/reason
2022-01-18 01833, 2022
monkey
Well, that's just rst and served on readthedocs, which I guess is just that but doesn't have the interactivity
it's like a preprocessor that runs python. great way to generate docs which contain the output of running a real function, instead of having to manually copy/paste values in
2022-01-18 01804, 2022
alastairp
monkey: oh, great! thanks for finding that. something to put in the potential tools pile
great. tell me when that's done and I'll give feedback direclty on 1477
2022-01-18 01841, 2022
alastairp
lucifer: the integration of the manage commands in 1477 look fine. The breakdown of the section is 1823 is good too. See the google doc, I proposed some replacement text for the top of the opening page. Underlined text is a proposal for the captions of the sections
2022-01-18 01831, 2022
reosarevok
mayhem: one thing I was thinking wouldn't hurt was some MeB-wide way of figuring out when someone's on holiday or whatever without having to check logs to see if they mentioned it some Monday :)
2022-01-18 01853, 2022
mayhem
we've tried this several times and then no one ever updates it.
2022-01-18 01857, 2022
reosarevok
Hmm, yeah, I guess that'd depend on people actually entering the info :D
2022-01-18 01835, 2022
lucifer
alastairp: đź‘Ť looking
2022-01-18 01828, 2022
alastairp
lucifer: I just added "alert handling" to the sysadmin section too - based on the work that the MB team did a few weeks ago, and prompted by mayhem's wish to have something similar for LB + others
2022-01-18 01852, 2022
mayhem
wish is such a polite way of describing that situation. :)
2022-01-18 01813, 2022
alastairp
"so that mayhem doesn't ask us in 4 months time whatever happened to that thing we were supposed to do"
2022-01-18 01813, 2022
alastairp
mayhem: I just added some subheadings to this - "What do we currently get alerts for?", "What things do we not get alerts for that we should add?". if any items in those 2 sections occur to you then please add them
2022-01-18 01823, 2022
mayhem
which doc?
2022-01-18 01830, 2022
mayhem has far too many docs open right now
2022-01-18 01845, 2022
mayhem
oh, I see it now.
2022-01-18 01845, 2022
alastairp
the docsprint overview one from yesterday
2022-01-18 01844, 2022
mayhem
hmmm. how does this differentiate from the monitoring already setup?
2022-01-18 01805, 2022
mayhem
because site inaccessible is already covered by the general infrastructure.
2022-01-18 01829, 2022
mayhem
so, it might make sense to keep in mind what already exists as part of the hetzner setup.
2022-01-18 01857, 2022
alastairp
right - I was thinking specifically of documentation that says "when we get a telegram notification that says x, try these steps to resolve it"
2022-01-18 01814, 2022
alastairp
rather than "we have monitoring set up for sites and it works like this"
2022-01-18 01827, 2022
mayhem
ok, lets augment the text above the lists to reflect that please.
Using Redoc to serve an interactive doc page based on sphinx docs
2022-01-18 01818, 2022
reosarevok
Well, MB is not python based, so that's why I was wondering, but I guess if we had a read the docs install we could probably also make something like that page
2022-01-18 01848, 2022
monkey
Possibly, I suppose it would work with any sphinx-based system
2022-01-18 01834, 2022
monkey
I'm not well versed with sphinx, so no assurances, but that's how it reads to me
2022-01-18 01847, 2022
alastairp
I think you'll only need the api specification + redoc
2022-01-18 01835, 2022
reosarevok
Wonder how (if at all) openapi can be used with stuff like inc=
2022-01-18 01841, 2022
alastairp
sphinx is just because that's what's used to generate other parts of python documentation (.rst files -> html). the extension that monkey linked to appears to just take the html/js that redoc generates and embed it in the same html output that sphinx makes
2022-01-18 01849, 2022
reosarevok
(maybe it's meant to only work for apis following their standards)
2022-01-18 01826, 2022
alastairp
reosarevok: without looking at any documentation I'd say that should be fine? it's just a list of possible values that a parameter can be set to
yvanzo: I see you write about autogenerating from MMD
2022-01-18 01817, 2022
reosarevok
Is that really doable? I mean, MMD indicates *everything* that can be returned, but can we autogenerate that "if you ask for inc=tags tags will be shown, otherwise not"?
2022-01-18 01837, 2022
alastairp
oh, I see - this "redocly" company has a tool to generate docs from openapi specifications, and if you want a "Try-it console" you need their paid version
reosarevok: Yes MMD is probably not enough but can likely part of the solution. I partly copied comments from the previous ticket, and added parenthesis around the MMD part because of this.
2022-01-18 01810, 2022
yvanzo
I just reorganized tickets so that we can distinguish between maintaining the current Wikidocs (still needed for now) and the future API docs platform.
2022-01-18 01858, 2022
reosarevok
Sure :)
2022-01-18 01851, 2022
CatQuest
[14:42] <reosarevok> We could even still have the wiki as a place to amend docs, but when the team sees changes and we agree with them, we transfer them to github
2022-01-18 01851, 2022
CatQuest
+100
2022-01-18 01845, 2022
CatQuest
[14:55] <reosarevok> ... can we move yesterday?
2022-01-18 01845, 2022
CatQuest
[14:58] <yvanzo> Sure, it also has time-traveling feature ;)
2022-01-18 01845, 2022
CatQuest
lmao
2022-01-18 01842, 2022
lucifer
alastairp: thanks will take a look at the alerts page too.
monkey: did you remove the y from my "sysadminy title" :)
2022-01-18 01837, 2022
monkey
I did !
2022-01-18 01838, 2022
yvanzo
alastairp: your suggestion for alerts handling seem to be similar to PR #45 to syswiki.
2022-01-18 01852, 2022
monkey
(but for BB)
2022-01-18 01815, 2022
reosarevok
What do you think about keeping the display but removing actions for non-admins vs doing something else?
2022-01-18 01852, 2022
yvanzo
zas: Would you want to include some items we discussed into the current docsprint?
2022-01-18 01854, 2022
alastairp
yvanzo: great. yes - the specific item that I added to the planning doc was how to make this exact document for listenbrainz
2022-01-18 01801, 2022
alastairp
thanks for pointing it to me
2022-01-18 01823, 2022
zas
yvanzo: which items are you thinking about? about alert system(s)?
2022-01-18 01856, 2022
yvanzo
Yes, for example trying to roughly list which procedures and requirements for running services.
2022-01-18 01807, 2022
yvanzo
+should be documented
2022-01-18 01819, 2022
yvanzo
This would be help with finding what each project is missing out.
2022-01-18 01858, 2022
yvanzo
We can all participate to it on tomorrow evening but I guess you would be the most knowledgeable about deployment/production environment.
2022-01-18 01859, 2022
mayhem
zas: The load on purple seems to be half of what is used to be. Hovers round load 6-7 now and seems pretty stable.
2022-01-18 01830, 2022
yvanzo
zas: also maybe having guidelines about image tags you are already using?
2022-01-18 01801, 2022
zas
yup
2022-01-18 01822, 2022
mayhem
zas: got a moment?
2022-01-18 01830, 2022
zas
yes
2022-01-18 01828, 2022
reosarevok
yvanzo: we could just make the lists under https://musicbrainz.org/admin/attributes all public, really, just dunno if that'd mean moving them out of /admin/attributes into just /attributes or something else :)
2022-01-18 01833, 2022
reosarevok
(bitmap too ^)
2022-01-18 01849, 2022
mayhem
I am writing the document that deals with me, my mobile phone and the banking tokens ending up in the indian ocean.
2022-01-18 01818, 2022
mayhem
everything in this recovery plan hinges on one thing and one thing only: that you can change the password and 2FA on my email account.
2022-01-18 01841, 2022
mayhem
can you log into the google workspace console and check to make sure that you could do that, if needed?
2022-01-18 01854, 2022
zas
let me check
2022-01-18 01823, 2022
mayhem
I shared this doc with you and reo, who are going to be key people in this game.
2022-01-18 01846, 2022
mayhem
but this document should not really be public. its a how to document on how to rob us.
2022-01-18 01806, 2022
reosarevok
Rob us of Rob?
2022-01-18 01834, 2022
reosarevok
I'll take a look too :)
2022-01-18 01849, 2022
mayhem
You'll have been robbed of rob when the time comes, but we want to prevent the robing of not rob before the rubbing of rob.
