1 00:00:05,239 --> 00:00:07,259 [music] 2 00:00:09,825 --> 00:00:11,845 [music] 3 00:00:15,120 --> 00:00:17,119 one. Uh, I'm Katney and this is 4 00:00:17,119 --> 00:00:19,359 switching from Sphinx to Markdown. Today 5 00:00:19,359 --> 00:00:20,640 I'm going to talk about restructured 6 00:00:20,640 --> 00:00:22,480 text and markdown, the associated 7 00:00:22,480 --> 00:00:24,400 documentation options, and what goes 8 00:00:24,400 --> 00:00:26,080 into migrating a substantial existing 9 00:00:26,080 --> 00:00:27,680 set of documentation from the first to 10 00:00:27,680 --> 00:00:29,840 the second. This project involves 11 00:00:29,840 --> 00:00:31,199 several tools which are mentioned 12 00:00:31,199 --> 00:00:32,880 throughout this talk and you can find a 13 00:00:32,880 --> 00:00:34,640 full list of resources linked at the end 14 00:00:34,640 --> 00:00:36,800 of the talk. You may be aware of the 15 00:00:36,800 --> 00:00:38,800 make docs documentation system due to 16 00:00:38,800 --> 00:00:40,239 the shift currently happening in the 17 00:00:40,239 --> 00:00:42,399 ecosystem. I will be expanding on that 18 00:00:42,399 --> 00:00:44,160 towards the end. The thing to know 19 00:00:44,160 --> 00:00:46,160 heading into this is that everything I 20 00:00:46,160 --> 00:00:47,760 discussed today is still applicable and 21 00:00:47,760 --> 00:00:50,960 re relevant. First, a bit about me. The 22 00:00:50,960 --> 00:00:52,480 important thing you need to know is that 23 00:00:52,480 --> 00:00:54,320 I am tolerated by a cat and three 24 00:00:54,320 --> 00:00:56,239 kittens who continue to let me live with 25 00:00:56,239 --> 00:00:58,879 them. Beyond that, in my work life, I am 26 00:00:58,879 --> 00:01:00,640 the superpowers community engineer with 27 00:01:00,640 --> 00:01:02,160 Prime Radiant, where I'm working to 28 00:01:02,160 --> 00:01:03,600 engage with our users and build a 29 00:01:03,600 --> 00:01:05,600 sustainable community. In another part 30 00:01:05,600 --> 00:01:07,119 of my life, I'm a core developer on the 31 00:01:07,119 --> 00:01:08,880 Beware project, where my primary focus 32 00:01:08,880 --> 00:01:10,720 is documentation, and I acted as the 33 00:01:10,720 --> 00:01:12,400 technical project manager for the Bware 34 00:01:12,400 --> 00:01:14,320 documentation infrastructure migration 35 00:01:14,320 --> 00:01:15,760 from, wouldn't you know it, to 36 00:01:15,760 --> 00:01:17,520 restructured text and sphinx to make 37 00:01:17,520 --> 00:01:20,560 docs and markdown. Before I start, you 38 00:01:20,560 --> 00:01:22,640 may have noticed from my accent that I 39 00:01:22,640 --> 00:01:24,560 am not from around here. I'd like to 40 00:01:24,560 --> 00:01:25,840 acknowledge that I am from the lands of 41 00:01:25,840 --> 00:01:27,600 the Bodawadmi and Ottawa peoples, 42 00:01:27,600 --> 00:01:29,520 otherwise known as Southeast Michigan, 43 00:01:29,520 --> 00:01:31,600 US. And I'd like to recognize that we 44 00:01:31,600 --> 00:01:32,720 are meeting today on the lands of the 45 00:01:32,720 --> 00:01:34,159 Turbo people to recognize their 46 00:01:34,159 --> 00:01:35,520 continuing connection to their lands, 47 00:01:35,520 --> 00:01:37,280 water, and culture and pay my respects 48 00:01:37,280 --> 00:01:38,880 to their elders, past, present, and 49 00:01:38,880 --> 00:01:41,119 emerging. 50 00:01:41,119 --> 00:01:44,320 Restructured text or rest, not Rust, but 51 00:01:44,320 --> 00:01:46,799 REST is a markup language primarily used 52 00:01:46,799 --> 00:01:48,240 for documentation in the Python 53 00:01:48,240 --> 00:01:50,479 ecosystem, though it has seen adoption 54 00:01:50,479 --> 00:01:53,200 elsewhere as well. Python needed a 55 00:01:53,200 --> 00:01:55,119 better way to do documentation than the 56 00:01:55,119 --> 00:01:57,600 existing Lattebased solution. REST was 57 00:01:57,600 --> 00:02:00,240 designed with Python's docs in mind. 58 00:02:00,240 --> 00:02:02,000 Sphinx is a documentation generator 59 00:02:02,000 --> 00:02:04,320 developed for and used by the Python 60 00:02:04,320 --> 00:02:05,920 ecosystem, though it has also seen 61 00:02:05,920 --> 00:02:08,879 adoption in other various projects. REST 62 00:02:08,879 --> 00:02:11,200 gives you a format for a single file and 63 00:02:11,200 --> 00:02:12,800 provides a way to describe a block of 64 00:02:12,800 --> 00:02:15,680 text as for example bold, italics, or a 65 00:02:15,680 --> 00:02:18,160 paragraph. Sphinx lets you create a 66 00:02:18,160 --> 00:02:19,680 related set of documents that are 67 00:02:19,680 --> 00:02:21,520 interlin with additional tooling for 68 00:02:21,520 --> 00:02:23,360 specific things like uh API 69 00:02:23,360 --> 00:02:24,959 documentation. 70 00:02:24,959 --> 00:02:26,400 One of the reasons that REST is still 71 00:02:26,400 --> 00:02:28,800 used in the Python ecosystem is because 72 00:02:28,800 --> 00:02:30,560 it is a capable tool with extensive 73 00:02:30,560 --> 00:02:32,239 history as the Python documentation 74 00:02:32,239 --> 00:02:35,519 format. Uh REST has been used for Python 75 00:02:35,519 --> 00:02:39,120 for 23 years and Spinx for 18 years. 76 00:02:39,120 --> 00:02:42,560 CPython 2.6 replaced Latte with Spinx. 77 00:02:42,560 --> 00:02:44,640 Other projects such as Django and Beware 78 00:02:44,640 --> 00:02:46,239 have continued to use it because it was 79 00:02:46,239 --> 00:02:48,400 used by everything that came before it. 80 00:02:48,400 --> 00:02:51,440 There are however alternatives. 81 00:02:51,440 --> 00:02:53,599 Markdown is also a markup language for 82 00:02:53,599 --> 00:02:56,080 creating formatted text. It was designed 83 00:02:56,080 --> 00:02:58,160 to be human readable, human writable 84 00:02:58,160 --> 00:03:00,400 solution to document uh documentation 85 00:03:00,400 --> 00:03:02,480 formatting that can easily be converted 86 00:03:02,480 --> 00:03:04,879 to HTML. It was originally written to 87 00:03:04,879 --> 00:03:07,120 simplify blogging. The web is based on 88 00:03:07,120 --> 00:03:09,440 HTML as a markup language, but HTML is 89 00:03:09,440 --> 00:03:11,120 verbose and unwieldy for a human to 90 00:03:11,120 --> 00:03:12,319 write. 91 00:03:12,319 --> 00:03:13,920 If you're writing a blog, you need to be 92 00:03:13,920 --> 00:03:15,840 able to produce HTML quickly. This is 93 00:03:15,840 --> 00:03:17,920 where Markdown came in. However, it's 94 00:03:17,920 --> 00:03:20,480 become much more widely used. Markdown 95 00:03:20,480 --> 00:03:22,319 has been adopted across many tech 96 00:03:22,319 --> 00:03:24,319 ecosystems. Nearly all messaging 97 00:03:24,319 --> 00:03:26,000 platforms, including apps like Slack and 98 00:03:26,000 --> 00:03:28,080 Discord, use it to support me or format 99 00:03:28,080 --> 00:03:30,319 messages. Many text and code editors not 100 00:03:30,319 --> 00:03:32,000 only support it, they include a 101 00:03:32,000 --> 00:03:34,000 rendering preview available. GitHub 102 00:03:34,000 --> 00:03:36,000 chose Markdown to be the default uh 103 00:03:36,000 --> 00:03:37,920 format, going so far as to de develop 104 00:03:37,920 --> 00:03:39,440 their own flavor. GitHub flavored 105 00:03:39,440 --> 00:03:42,319 Markdown. AI is all built around 106 00:03:42,319 --> 00:03:44,159 processing human readable text. The 107 00:03:44,159 --> 00:03:45,599 simplicity of markdown being able to 108 00:03:45,599 --> 00:03:47,680 move to HTML from text has worked to its 109 00:03:47,680 --> 00:03:50,159 advantage in the AI processing pipeline. 110 00:03:50,159 --> 00:03:52,159 If you look at the UIs for LLMs such as 111 00:03:52,159 --> 00:03:54,239 claude or chatgpt, they all accept 112 00:03:54,239 --> 00:03:56,879 markdown formatting. Markdown is now a 113 00:03:56,879 --> 00:03:58,239 viable alternative to rest for 114 00:03:58,239 --> 00:03:59,920 documentation due to the development of 115 00:03:59,920 --> 00:04:02,640 various tools. There are several options 116 00:04:02,640 --> 00:04:04,560 including platforms such as make docs, 117 00:04:04,560 --> 00:04:08,159 docsify, docuous, gitbook and tdo as 118 00:04:08,159 --> 00:04:09,680 well as sphinx when using the mist 119 00:04:09,680 --> 00:04:12,959 parser. Essentially make docs etc is to 120 00:04:12,959 --> 00:04:16,639 markdown as sphinx is to rest. 121 00:04:16,639 --> 00:04:19,840 In terms of what rest does well it 122 00:04:19,840 --> 00:04:21,600 provides a rich cross referencing of 123 00:04:21,600 --> 00:04:23,600 multiple documents of content. It was 124 00:04:23,600 --> 00:04:25,759 for a long time the only option for uh 125 00:04:25,759 --> 00:04:27,520 using sphinx the combination of which 126 00:04:27,520 --> 00:04:29,199 was the only backend supported by read 127 00:04:29,199 --> 00:04:31,680 the docs. As for difficulties it 128 00:04:31,680 --> 00:04:33,280 presents, it was not concerned with 129 00:04:33,280 --> 00:04:35,440 being human readable. Link syntax is 130 00:04:35,440 --> 00:04:37,600 obtuse at best. It's very whites space 131 00:04:37,600 --> 00:04:39,040 sensitive and doesn't allow for markup 132 00:04:39,040 --> 00:04:40,639 in the link text, including formatting 133 00:04:40,639 --> 00:04:43,520 text as code. This is an example of a 134 00:04:43,520 --> 00:04:46,320 simple document formatted using REST. It 135 00:04:46,320 --> 00:04:48,000 contains a document heading followed by 136 00:04:48,000 --> 00:04:49,840 a paragraph that includes bold text, 137 00:04:49,840 --> 00:04:52,240 strikethrough text, and a web link. The 138 00:04:52,240 --> 00:04:54,400 strike ro and class must be included at 139 00:04:54,400 --> 00:04:56,240 the top to render strike through text. 140 00:04:56,240 --> 00:04:58,160 However, that doesn't even work on its 141 00:04:58,160 --> 00:05:00,400 own. It requires a separate CSS element 142 00:05:00,400 --> 00:05:02,560 to successfully render. The number of 143 00:05:02,560 --> 00:05:04,000 equal signs around the heading must 144 00:05:04,000 --> 00:05:05,280 always match the length of the heading 145 00:05:05,280 --> 00:05:06,960 text. And so you have to remember to 146 00:05:06,960 --> 00:05:09,120 update that if you alter the text. To 147 00:05:09,120 --> 00:05:10,800 render properly, the link must include 148 00:05:10,800 --> 00:05:12,400 the back ticks, the space between the 149 00:05:12,400 --> 00:05:14,320 text and the URL, the brackets, and the 150 00:05:14,320 --> 00:05:16,400 final underscore. 151 00:05:16,400 --> 00:05:18,320 As for what markdown does well, it was 152 00:05:18,320 --> 00:05:19,759 designed to be human readable and easily 153 00:05:19,759 --> 00:05:21,840 converted to HTML. Reference links are 154 00:05:21,840 --> 00:05:23,280 written in a way that flow naturally and 155 00:05:23,280 --> 00:05:25,600 allows markup in the link text. The rest 156 00:05:25,600 --> 00:05:27,120 of the syntax is pretty straightforward 157 00:05:27,120 --> 00:05:29,520 and can typically be picked up quickly. 158 00:05:29,520 --> 00:05:31,360 It's much closer practically speaking to 159 00:05:31,360 --> 00:05:32,720 how you would write a text document 160 00:05:32,720 --> 00:05:35,280 using asy based emphasis. As for 161 00:05:35,280 --> 00:05:36,720 difficulties it presents, there are 162 00:05:36,720 --> 00:05:38,320 generally no there's generally no 163 00:05:38,320 --> 00:05:39,919 agreement on what the canonical flavor 164 00:05:39,919 --> 00:05:42,639 of markdown is. The creator and much of 165 00:05:42,639 --> 00:05:44,240 the community have actively worked 166 00:05:44,240 --> 00:05:46,800 against the idea. As a result, there are 167 00:05:46,800 --> 00:05:48,720 several competing flavors. The closest 168 00:05:48,720 --> 00:05:51,199 to a standard is common mark, but it has 169 00:05:51,199 --> 00:05:53,280 not been fully adopted. In terms of use 170 00:05:53,280 --> 00:05:55,360 for documentation, make docs and other 171 00:05:55,360 --> 00:05:56,880 tools were not developed until 172 00:05:56,880 --> 00:06:00,080 relatively recently relative to Sphinx. 173 00:06:00,080 --> 00:06:01,840 This is the same document formatted in 174 00:06:01,840 --> 00:06:03,680 markdown. Heading levels are determined 175 00:06:03,680 --> 00:06:05,039 by the number of hashes at the beginning 176 00:06:05,039 --> 00:06:06,960 of the line. Link text is included in 177 00:06:06,960 --> 00:06:08,800 square brackets immediately followed uh 178 00:06:08,800 --> 00:06:12,240 by the link target in parenthesis. So 179 00:06:12,240 --> 00:06:14,319 which one is better? Both REST and 180 00:06:14,319 --> 00:06:15,680 Markdown clearly have strengths and 181 00:06:15,680 --> 00:06:18,319 weaknesses. As with many things, it 182 00:06:18,319 --> 00:06:20,720 depends on your situation. That said, 183 00:06:20,720 --> 00:06:22,479 the overwhelming adoption of markdown by 184 00:06:22,479 --> 00:06:24,560 a broad range of ecosystems speak to it 185 00:06:24,560 --> 00:06:27,120 cap its capabilities. I would argue that 186 00:06:27,120 --> 00:06:28,160 if ease of maintenance and 187 00:06:28,160 --> 00:06:29,759 approachability are important to your 188 00:06:29,759 --> 00:06:32,080 project, markdown is a better choice. 189 00:06:32,080 --> 00:06:33,919 I'm not suggesting that Sphinx unrest 190 00:06:33,919 --> 00:06:36,400 are bad. I am however saying that it can 191 00:06:36,400 --> 00:06:38,240 become easier to make a decision to make 192 00:06:38,240 --> 00:06:40,319 a major shift when you are adapting to 193 00:06:40,319 --> 00:06:43,120 the overall flow of change. 194 00:06:43,120 --> 00:06:45,039 The Beware documentation migration 195 00:06:45,039 --> 00:06:46,720 really began two years ago, though the 196 00:06:46,720 --> 00:06:48,720 bulk of it is more recent. For a little 197 00:06:48,720 --> 00:06:50,560 context, Beware is a suite of tools 198 00:06:50,560 --> 00:06:52,319 designed to enable you to write 199 00:06:52,319 --> 00:06:54,240 crossplatform gly applications entirely 200 00:06:54,240 --> 00:06:56,639 in Python. You probably know the project 201 00:06:56,639 --> 00:06:58,160 lead, Russell Keith McGee, sitting here 202 00:06:58,160 --> 00:07:00,639 in the front row. I decided to start 203 00:07:00,639 --> 00:07:02,560 contributing at the sprints at PyCon US 204 00:07:02,560 --> 00:07:04,560 2024. I struggled to find the 205 00:07:04,560 --> 00:07:06,080 documentation while preparing for my 206 00:07:06,080 --> 00:07:07,919 first call with Russell. This issue 207 00:07:07,919 --> 00:07:09,360 became the topic of the call and 208 00:07:09,360 --> 00:07:11,120 subsequently my primary contribution 209 00:07:11,120 --> 00:07:13,039 focus. Fast forward to the leadup to 210 00:07:13,039 --> 00:07:15,759 Pyon US 2025. we were dealing with an 211 00:07:15,759 --> 00:07:17,360 issue related to rest. And Russell 212 00:07:17,360 --> 00:07:19,680 remarked, "Once upon a time, rest seemed 213 00:07:19,680 --> 00:07:21,280 like a good idea, but I'm increasingly 214 00:07:21,280 --> 00:07:22,639 thinking that markdown, moving to 215 00:07:22,639 --> 00:07:24,000 Markdown across the board would be worth 216 00:07:24,000 --> 00:07:25,680 it." When I followed up with full 217 00:07:25,680 --> 00:07:27,440 support, he quipped, "If only we had a 218 00:07:27,440 --> 00:07:30,400 sprint coming up." Little did he know. 219 00:07:30,400 --> 00:07:32,319 That said, moving to Markdown across the 220 00:07:32,319 --> 00:07:35,120 board was not going to be a simple task. 221 00:07:35,120 --> 00:07:36,880 Beware is not a single library. It's 222 00:07:36,880 --> 00:07:38,240 multiple tools working under an 223 00:07:38,240 --> 00:07:40,080 umbrella. The Beware project has a 224 00:07:40,080 --> 00:07:41,440 website, and each of the tools have 225 00:07:41,440 --> 00:07:43,599 their own documentation. We use read the 226 00:07:43,599 --> 00:07:45,039 docs and GitHub pages for web 227 00:07:45,039 --> 00:07:47,280 deployment. The beware documentation 228 00:07:47,280 --> 00:07:49,039 infrastructure falls into four major 229 00:07:49,039 --> 00:07:50,560 categories. 230 00:07:50,560 --> 00:07:52,960 The tutorial, the three major tools, 231 00:07:52,960 --> 00:07:55,680 Toga Briefcase and Rubicon Objective C, 232 00:07:55,680 --> 00:07:58,080 various standalone documents, and the 233 00:07:58,080 --> 00:08:00,160 website. This documentation structure 234 00:08:00,160 --> 00:08:01,919 may not necessarily be representative of 235 00:08:01,919 --> 00:08:03,840 your situation as many projects only 236 00:08:03,840 --> 00:08:06,000 have one set of documentation. I'm going 237 00:08:06,000 --> 00:08:07,440 to share my experience shifting the 238 00:08:07,440 --> 00:08:09,120 beware documentation from REST to 239 00:08:09,120 --> 00:08:10,960 Sphinx, Rest and Sphinx to Markdown and 240 00:08:10,960 --> 00:08:13,199 Make Docs. I began with the website 241 00:08:13,199 --> 00:08:14,960 content. 242 00:08:14,960 --> 00:08:16,560 This conversion took a few hours at the 243 00:08:16,560 --> 00:08:19,520 Pyon US 2025 sprints. The Beware website 244 00:08:19,520 --> 00:08:20,960 was originally built using a system 245 00:08:20,960 --> 00:08:23,280 called Lecter. Lecter is a website 246 00:08:23,280 --> 00:08:24,960 builder that is halfway between a 247 00:08:24,960 --> 00:08:26,800 content management system and a static 248 00:08:26,800 --> 00:08:29,280 site generator. It defaults to markdown 249 00:08:29,280 --> 00:08:31,599 for content. When the Beware website was 250 00:08:31,599 --> 00:08:33,200 created, Russell went to great lengths 251 00:08:33,200 --> 00:08:35,200 to get it into restructured text mode to 252 00:08:35,200 --> 00:08:36,240 align with the rest of the 253 00:08:36,240 --> 00:08:38,000 documentation, which as I mentioned 254 00:08:38,000 --> 00:08:40,000 earlier seemed like a good idea at the 255 00:08:40,000 --> 00:08:42,159 time. This was now a very frustrating 256 00:08:42,159 --> 00:08:43,519 feature and that made it a good first 257 00:08:43,519 --> 00:08:45,200 target for testing the viability of 258 00:08:45,200 --> 00:08:47,680 migration. The tools I used for this 259 00:08:47,680 --> 00:08:49,360 were a markup format converter called 260 00:08:49,360 --> 00:08:51,279 pandoc and a couple of features from the 261 00:08:51,279 --> 00:08:53,600 lectctor API. The rest content was 262 00:08:53,600 --> 00:08:55,519 extracted using the API and converted 263 00:08:55,519 --> 00:08:58,000 using pandock. The most important thing 264 00:08:58,000 --> 00:08:59,519 to come out of this was proof that it 265 00:08:59,519 --> 00:09:01,279 was possible to convert rest to markdown 266 00:09:01,279 --> 00:09:03,440 with some level of automation. This 267 00:09:03,440 --> 00:09:05,200 opened the door for migrating the entire 268 00:09:05,200 --> 00:09:07,680 documentation infrastructure. 269 00:09:07,680 --> 00:09:09,360 Preparation for the pull project took 270 00:09:09,360 --> 00:09:11,279 about one and a half months. When I 271 00:09:11,279 --> 00:09:12,720 began this process, the switch to 272 00:09:12,720 --> 00:09:15,440 markdown was not guaranteed. My job was 273 00:09:15,440 --> 00:09:17,279 to explore the potential and prove it 274 00:09:17,279 --> 00:09:19,519 was possible. I went into this with an 275 00:09:19,519 --> 00:09:20,800 understanding that if I couldn't prove 276 00:09:20,800 --> 00:09:22,160 viability, the project would be 277 00:09:22,160 --> 00:09:24,480 scrapped. There were several pieces to 278 00:09:24,480 --> 00:09:26,160 this process, the details of which I 279 00:09:26,160 --> 00:09:28,160 will get into in the next sections. This 280 00:09:28,160 --> 00:09:30,080 included considering our back-end 281 00:09:30,080 --> 00:09:32,320 options, choosing and investigating make 282 00:09:32,320 --> 00:09:34,320 docs, creating a custom translation 283 00:09:34,320 --> 00:09:36,399 solution, exploring add-ons that we 284 00:09:36,399 --> 00:09:38,000 would need to shape our docs, 285 00:09:38,000 --> 00:09:39,440 customizing and writing various 286 00:09:39,440 --> 00:09:41,519 migration tools, and choosing what tools 287 00:09:41,519 --> 00:09:43,040 we needed to replace various checks we 288 00:09:43,040 --> 00:09:44,560 were doing, and putting together a repo 289 00:09:44,560 --> 00:09:47,839 for shared content and tooling. 290 00:09:47,839 --> 00:09:49,519 The initial discussion involved a list 291 00:09:49,519 --> 00:09:51,760 of requirements and ideal features. 292 00:09:51,760 --> 00:09:53,839 Requirements included that it be the 293 00:09:53,839 --> 00:09:56,000 documentation be a static site, that the 294 00:09:56,000 --> 00:09:58,080 platform support translations, and that 295 00:09:58,080 --> 00:10:00,640 the overall setup have at the very least 296 00:10:00,640 --> 00:10:03,200 basic feature parody with Sphinx. High 297 00:10:03,200 --> 00:10:04,800 on the list of ideal features was 298 00:10:04,800 --> 00:10:07,680 documentation of type aliases. With that 299 00:10:07,680 --> 00:10:10,720 in mind, I considered our options. 300 00:10:10,720 --> 00:10:12,399 Sphinx does actually have content 301 00:10:12,399 --> 00:10:14,800 support for markdown. However, the API 302 00:10:14,800 --> 00:10:16,160 documentation still requires 303 00:10:16,160 --> 00:10:17,920 restructured text. So you're then 304 00:10:17,920 --> 00:10:19,760 dealing with REST on top of now dealing 305 00:10:19,760 --> 00:10:21,519 with inconsistency in your documentation 306 00:10:21,519 --> 00:10:24,240 formatting. Make docs is a static site 307 00:10:24,240 --> 00:10:25,680 generator built around markdown and 308 00:10:25,680 --> 00:10:27,920 aimed at documentation. It definitely 309 00:10:27,920 --> 00:10:30,560 had the potential to fit our needs. As 310 00:10:30,560 --> 00:10:31,839 you look at other projects that are 311 00:10:31,839 --> 00:10:33,760 actively being developed, make docs 312 00:10:33,760 --> 00:10:34,959 comes out as the most common 313 00:10:34,959 --> 00:10:37,519 documentation solution. This this 314 00:10:37,519 --> 00:10:39,600 features projects such as fast API, 315 00:10:39,600 --> 00:10:41,600 textual enrich, CI buildhe, and 316 00:10:41,600 --> 00:10:43,920 paidantic. I was offered the opportunity 317 00:10:43,920 --> 00:10:46,320 to look into alternatives and I chose to 318 00:10:46,320 --> 00:10:48,800 dig into make docs first. 319 00:10:48,800 --> 00:10:50,320 The first step was to learn the basics 320 00:10:50,320 --> 00:10:52,560 of working with make docs. Once I had 321 00:10:52,560 --> 00:10:54,640 that down, I needed to establish basic 322 00:10:54,640 --> 00:10:56,880 feature parity with Sphinx. Verifying 323 00:10:56,880 --> 00:10:58,399 that the most basic features of Sphinx 324 00:10:58,399 --> 00:11:00,079 were available was a quick process. 325 00:11:00,079 --> 00:11:01,680 Establishing full feature parity would 326 00:11:01,680 --> 00:11:04,240 take much longer. I chose early on to 327 00:11:04,240 --> 00:11:06,160 figure out documenting type aliases. 328 00:11:06,160 --> 00:11:07,680 Russell mentioned offhand that if this 329 00:11:07,680 --> 00:11:08,880 was doable, it would mean instant 330 00:11:08,880 --> 00:11:11,200 approval of the change. This is because 331 00:11:11,200 --> 00:11:12,640 there are some features that the current 332 00:11:12,640 --> 00:11:14,160 Python typing experience that are not 333 00:11:14,160 --> 00:11:16,480 well supported by Sphinx autodoc. While 334 00:11:16,480 --> 00:11:18,160 I knew this wouldn't actually guarantee 335 00:11:18,160 --> 00:11:19,760 approval, I'm always up for a challenge. 336 00:11:19,760 --> 00:11:21,360 And while it took some doing, I was able 337 00:11:21,360 --> 00:11:23,680 to get it working. One of the things we 338 00:11:23,680 --> 00:11:25,440 discovered early in the process is that 339 00:11:25,440 --> 00:11:27,120 the live preview build was quicker and 340 00:11:27,120 --> 00:11:29,440 more responsive than Spinx had been. As 341 00:11:29,440 --> 00:11:31,680 well, unlike Spinx, Make Docs was 342 00:11:31,680 --> 00:11:33,040 capable of tracking changes to the 343 00:11:33,040 --> 00:11:34,800 documentation in the source code in the 344 00:11:34,800 --> 00:11:36,959 live build without any decrease in 345 00:11:36,959 --> 00:11:38,640 performance. 346 00:11:38,640 --> 00:11:40,000 Another important piece of this was 347 00:11:40,000 --> 00:11:41,760 choosing a theme. There were several 348 00:11:41,760 --> 00:11:43,360 available. However, material for make 349 00:11:43,360 --> 00:11:44,959 docs had the most useful features and 350 00:11:44,959 --> 00:11:46,240 appeared to be the most actively 351 00:11:46,240 --> 00:11:48,560 developed. I was confident at this point 352 00:11:48,560 --> 00:11:50,000 that a majority of what we needed was 353 00:11:50,000 --> 00:11:51,760 feasible with make docs. With basic 354 00:11:51,760 --> 00:11:53,519 viability established, I turned to 355 00:11:53,519 --> 00:11:55,360 translations. 356 00:11:55,360 --> 00:11:57,680 Make docs had a multilingual story, but 357 00:11:57,680 --> 00:11:59,680 no real translation story. The 358 00:11:59,680 --> 00:12:02,240 recommendation for translating involved 359 00:12:02,240 --> 00:12:04,800 having a local static translated copy of 360 00:12:04,800 --> 00:12:07,200 your entire site in markdown for every 361 00:12:07,200 --> 00:12:09,680 language you required. This was not 362 00:12:09,680 --> 00:12:12,000 going to work for us. We were using an 363 00:12:12,000 --> 00:12:13,760 online communitydriven translation front 364 00:12:13,760 --> 00:12:15,680 end called Weblate. And in order to make 365 00:12:15,680 --> 00:12:17,200 efficient use of Weblate, you need to 366 00:12:17,200 --> 00:12:19,200 present content in a translatable form, 367 00:12:19,200 --> 00:12:22,480 which means using GNU get text PO files. 368 00:12:22,480 --> 00:12:24,240 I found the translate toolkit, which is 369 00:12:24,240 --> 00:12:25,839 a set of translation tools provided by 370 00:12:25,839 --> 00:12:27,760 the Weblate maintainer. They allow for 371 00:12:27,760 --> 00:12:30,079 converting between among other things PO 372 00:12:30,079 --> 00:12:32,399 files and markdown. 373 00:12:32,399 --> 00:12:34,240 Integrating the translation process into 374 00:12:34,240 --> 00:12:36,240 the build tooling would require writing 375 00:12:36,240 --> 00:12:37,920 wrappers around the translation and 376 00:12:37,920 --> 00:12:40,639 build commands. We use talks as a front 377 00:12:40,639 --> 00:12:42,399 end for executing project tasks in a 378 00:12:42,399 --> 00:12:43,600 clean environment for running the 379 00:12:43,600 --> 00:12:45,920 wrapper scripts. This meant among other 380 00:12:45,920 --> 00:12:47,360 things that we deployed the docu when we 381 00:12:47,360 --> 00:12:48,560 deployed the documentation to read the 382 00:12:48,560 --> 00:12:50,320 docs and GitHub pages that what we were 383 00:12:50,320 --> 00:12:52,079 running locally directly mirrored what 384 00:12:52,079 --> 00:12:53,760 was being run remotely. This was 385 00:12:53,760 --> 00:12:54,880 incredibly beneficial for 386 00:12:54,880 --> 00:12:56,079 troubleshooting build issues and 387 00:12:56,079 --> 00:12:58,959 failures. I was able to build a process 388 00:12:58,959 --> 00:13:00,720 that used the translated content of the 389 00:13:00,720 --> 00:13:02,639 PO files to generate the associated 390 00:13:02,639 --> 00:13:04,800 markdown in a temp directory, ran the 391 00:13:04,800 --> 00:13:06,959 make docs build process within and 392 00:13:06,959 --> 00:13:09,839 generated translated HTML. This solution 393 00:13:09,839 --> 00:13:11,680 would evolve as the migration pro uh 394 00:13:11,680 --> 00:13:13,360 progressed, but we were able to build on 395 00:13:13,360 --> 00:13:15,839 what I provided initially. 396 00:13:15,839 --> 00:13:17,920 To reproduce our existing documentation, 397 00:13:17,920 --> 00:13:19,279 I would need to employ a number of 398 00:13:19,279 --> 00:13:21,200 extensions and plugins. These are the 399 00:13:21,200 --> 00:13:23,920 ones common to all of our projects. The 400 00:13:23,920 --> 00:13:25,920 attribution list extension added syntax 401 00:13:25,920 --> 00:13:27,680 for defining attributes on the HTML 402 00:13:27,680 --> 00:13:30,000 output. This allowed me to apply CSS to 403 00:13:30,000 --> 00:13:31,920 any element by adding an ID within the 404 00:13:31,920 --> 00:13:34,639 markdown. Auto refs added syntax for 405 00:13:34,639 --> 00:13:37,279 simple linking between pages. 406 00:13:37,279 --> 00:13:39,440 Macros is a plug-in and mini framework 407 00:13:39,440 --> 00:13:41,040 meant to add macro and automation 408 00:13:41,040 --> 00:13:42,800 capabilities through the use of custom 409 00:13:42,800 --> 00:13:45,680 variables, macros, and filters. We made 410 00:13:45,680 --> 00:13:46,880 significant use of this add-on 411 00:13:46,880 --> 00:13:48,639 throughout the project. It enabled us to 412 00:13:48,639 --> 00:13:50,240 do things like customize the shared 413 00:13:50,240 --> 00:13:51,839 content experience through configuration 414 00:13:51,839 --> 00:13:53,839 variables and automate the content 415 00:13:53,839 --> 00:13:56,639 creation based on metadata. The basic 416 00:13:56,639 --> 00:13:58,320 navigation built into make docs wasn't 417 00:13:58,320 --> 00:14:00,480 sufficient for our needs. Literate nav 418 00:14:00,480 --> 00:14:02,240 allows you allows for specifying custom 419 00:14:02,240 --> 00:14:04,240 page navigation structures and markdown 420 00:14:04,240 --> 00:14:06,240 instead of within the yaml configuration 421 00:14:06,240 --> 00:14:09,120 files. For those familiar with sphinx, 422 00:14:09,120 --> 00:14:11,199 make dost strings is the equivalent of 423 00:14:11,199 --> 00:14:14,160 or the analog rather to sphinx autodoc. 424 00:14:14,160 --> 00:14:15,760 For those unfamiliar, this is the 425 00:14:15,760 --> 00:14:16,959 plug-in designed to extract your 426 00:14:16,959 --> 00:14:18,560 documentation from dock strings in your 427 00:14:18,560 --> 00:14:20,399 source code. It has extensive 428 00:14:20,399 --> 00:14:22,079 configuration options including things 429 00:14:22,079 --> 00:14:24,079 like overall formatting and how and what 430 00:14:24,079 --> 00:14:25,519 class and typing information is 431 00:14:25,519 --> 00:14:27,040 displayed. 432 00:14:27,040 --> 00:14:29,360 Pymdown extensions was critical called 433 00:14:29,360 --> 00:14:31,279 as pymdownx. It supplies several 434 00:14:31,279 --> 00:14:33,040 markdown formatting options including 435 00:14:33,040 --> 00:14:35,199 code syntax highlighting, admonitions, 436 00:14:35,199 --> 00:14:37,360 tabbed content and external content 437 00:14:37,360 --> 00:14:40,000 injection. The next step was automating 438 00:14:40,000 --> 00:14:42,320 the markdown conversion. 439 00:14:42,320 --> 00:14:44,079 Make docs makes use of quite a number of 440 00:14:44,079 --> 00:14:45,680 plugins and extensions as mentioned that 441 00:14:45,680 --> 00:14:48,240 apply to markdown formatting. Pandoc is 442 00:14:48,240 --> 00:14:50,160 by nature unaware of the existence of 443 00:14:50,160 --> 00:14:51,920 these add-ons and therefore doesn't know 444 00:14:51,920 --> 00:14:53,600 how to handle converting to exactly what 445 00:14:53,600 --> 00:14:55,839 we needed for our documentation. It took 446 00:14:55,839 --> 00:14:57,440 a lot of trial and error to figure out 447 00:14:57,440 --> 00:15:00,240 getting as close as possible. Pandock 448 00:15:00,240 --> 00:15:02,240 offers several markdown extensions that 449 00:15:02,240 --> 00:15:03,760 handle converting various elements of 450 00:15:03,760 --> 00:15:06,480 rest. Common Mark X is Pandock's 451 00:15:06,480 --> 00:15:08,320 implementation of Common Mark, which 452 00:15:08,320 --> 00:15:10,320 includes a specific set of the Pandock 453 00:15:10,320 --> 00:15:12,320 extensions to cover features that aren't 454 00:15:12,320 --> 00:15:15,440 strictly part of Commonark. Pandock is 455 00:15:15,440 --> 00:15:17,600 designed to be run on one file at a 456 00:15:17,600 --> 00:15:20,399 time. I used a find command with Pandock 457 00:15:20,399 --> 00:15:21,839 to enable running the command over all 458 00:15:21,839 --> 00:15:23,920 files in a directory. This is the 459 00:15:23,920 --> 00:15:26,720 command I used. As shown, it is possible 460 00:15:26,720 --> 00:15:28,720 to customize which extensions are 461 00:15:28,720 --> 00:15:30,800 included with Common MarkX. When running 462 00:15:30,800 --> 00:15:33,199 this pandoc command, 463 00:15:33,199 --> 00:15:34,800 I used pandock for the initial 464 00:15:34,800 --> 00:15:36,399 conversion, but that left quite a bit of 465 00:15:36,399 --> 00:15:38,480 work to do. I built a custom script of 466 00:15:38,480 --> 00:15:40,079 regular expressions to handle getting 467 00:15:40,079 --> 00:15:41,920 the pandock converted content into maked 468 00:15:41,920 --> 00:15:44,720 docs compatible state. This is one of 469 00:15:44,720 --> 00:15:47,440 the most obnoxious. 470 00:15:47,440 --> 00:15:49,040 I couldn't run pandock on the source 471 00:15:49,040 --> 00:15:50,560 code, so that meant converting dock 472 00:15:50,560 --> 00:15:51,920 strings entirely with regular 473 00:15:51,920 --> 00:15:54,079 expressions. Luckily, I found that there 474 00:15:54,079 --> 00:15:55,680 was a limited set of rest markup 475 00:15:55,680 --> 00:15:57,759 elements used in the dock strings. This 476 00:15:57,759 --> 00:15:59,360 task required special care to ensure 477 00:15:59,360 --> 00:16:01,360 that the source code was not altered and 478 00:16:01,360 --> 00:16:03,920 version control was invaluable here. The 479 00:16:03,920 --> 00:16:05,440 translations were also in a format that 480 00:16:05,440 --> 00:16:07,279 pandock wouldn't work with. So they also 481 00:16:07,279 --> 00:16:08,639 required a separate set of regular 482 00:16:08,639 --> 00:16:10,560 expressions. The biggest issue I ran 483 00:16:10,560 --> 00:16:12,079 into there was that we had several 484 00:16:12,079 --> 00:16:13,600 malformed rest links that were not 485 00:16:13,600 --> 00:16:16,320 caught by the previous checks. I wanted 486 00:16:16,320 --> 00:16:17,920 to make to be able to verify and 487 00:16:17,920 --> 00:16:19,920 maintain the consistency of our markdown 488 00:16:19,920 --> 00:16:22,639 content. I was introduced early on to a 489 00:16:22,639 --> 00:16:24,480 markdown llinter called Rundle which was 490 00:16:24,480 --> 00:16:26,720 very early in its development. It had a 491 00:16:26,720 --> 00:16:28,800 number of bugs, but also a phenomenal 492 00:16:28,800 --> 00:16:30,880 maintainer. They opted to include a 493 00:16:30,880 --> 00:16:32,399 maked doc setting that would encompass 494 00:16:32,399 --> 00:16:33,920 all the necessary features to work with 495 00:16:33,920 --> 00:16:35,600 maked docs compatible markdown, which 496 00:16:35,600 --> 00:16:36,880 we've worked together on improving 497 00:16:36,880 --> 00:16:39,279 throughout this project. I chose pi 498 00:16:39,279 --> 00:16:40,959 spelling for our spell checker. It was 499 00:16:40,959 --> 00:16:42,639 more opinionated than our existing spell 500 00:16:42,639 --> 00:16:44,240 checker and required a longer custom 501 00:16:44,240 --> 00:16:46,079 word list, but once we sorted that, it's 502 00:16:46,079 --> 00:16:48,480 worked very smoothly. And while it has 503 00:16:48,480 --> 00:16:50,079 other features, I'm using markdown 504 00:16:50,079 --> 00:16:52,079 checker specifically to verify that URLs 505 00:16:52,079 --> 00:16:54,959 are what web URLs are valid. As part of 506 00:16:54,959 --> 00:16:56,639 the preparation, one of the things we 507 00:16:56,639 --> 00:16:58,320 did was create a separate utilities 508 00:16:58,320 --> 00:17:00,800 project called Beware Docs Tools. We 509 00:17:00,800 --> 00:17:02,560 built a basic website that exercises 510 00:17:02,560 --> 00:17:04,000 many of the features used in the rest of 511 00:17:04,000 --> 00:17:06,400 the documentation. This provides us with 512 00:17:06,400 --> 00:17:08,559 a test bed where we can test the impact 513 00:17:08,559 --> 00:17:11,280 of changes ahead of the deployment. We 514 00:17:11,280 --> 00:17:12,559 use this as a single source of 515 00:17:12,559 --> 00:17:15,199 dependencies for all the documentation. 516 00:17:15,199 --> 00:17:17,039 We made a series of customizations to 517 00:17:17,039 --> 00:17:18,640 the theme and this allows us to keep 518 00:17:18,640 --> 00:17:20,480 that in one place and apply it across 519 00:17:20,480 --> 00:17:22,959 the board. The available tooling for 520 00:17:22,959 --> 00:17:25,039 injecting content from separate location 521 00:17:25,039 --> 00:17:27,039 into the documentation meant we could 522 00:17:27,039 --> 00:17:29,039 consolidate things like our contribution 523 00:17:29,039 --> 00:17:31,200 guide and style guides into one place 524 00:17:31,200 --> 00:17:32,960 and have the same documentation across 525 00:17:32,960 --> 00:17:35,760 all projects. All of the build tooling 526 00:17:35,760 --> 00:17:37,360 designed mostly around the translation 527 00:17:37,360 --> 00:17:39,360 solution is maintained here. Quite 528 00:17:39,360 --> 00:17:40,960 recently we were chasing down a bug in a 529 00:17:40,960 --> 00:17:42,880 tool called click and the pro and in the 530 00:17:42,880 --> 00:17:44,880 process found a workaround for it. The 531 00:17:44,880 --> 00:17:47,200 workaround involved adding a flag to the 532 00:17:47,200 --> 00:17:48,960 live serve tooling. If we weren't 533 00:17:48,960 --> 00:17:50,320 hosting all the build tooling in one 534 00:17:50,320 --> 00:17:51,840 repo, I would have had to deploy it 535 00:17:51,840 --> 00:17:53,760 across several. This is not the first 536 00:17:53,760 --> 00:17:55,120 example of this utilities project 537 00:17:55,120 --> 00:17:57,440 proving to have been a good choice. That 538 00:17:57,440 --> 00:17:58,880 covers what went into preparing for the 539 00:17:58,880 --> 00:18:01,039 overall migration. At that point, I was 540 00:18:01,039 --> 00:18:02,480 given the go-ahhead to migrate the 541 00:18:02,480 --> 00:18:04,080 tutorial. 542 00:18:04,080 --> 00:18:06,080 Once preparation was done, the actual 543 00:18:06,080 --> 00:18:08,960 tutorial migration took two weeks. The 544 00:18:08,960 --> 00:18:10,880 tutorial was a good first choice because 545 00:18:10,880 --> 00:18:12,640 it was relative to the rest of the pro 546 00:18:12,640 --> 00:18:15,120 documentation simple. While 547 00:18:15,120 --> 00:18:16,880 documentation features of the tutorial 548 00:18:16,880 --> 00:18:18,640 are basic, they are all relevant to the 549 00:18:18,640 --> 00:18:20,559 rest of the project. For example, it 550 00:18:20,559 --> 00:18:21,840 consists of eight sections that have 551 00:18:21,840 --> 00:18:23,760 interlinking between pages and includes 552 00:18:23,760 --> 00:18:26,400 codelocks and tabbed content. The 553 00:18:26,400 --> 00:18:28,320 tutorial was already fully translated 554 00:18:28,320 --> 00:18:30,320 primarily by human translators and we 555 00:18:30,320 --> 00:18:32,000 did our best to maintain as much of that 556 00:18:32,000 --> 00:18:34,160 content as possible. 557 00:18:34,160 --> 00:18:36,160 The Toga migration took the better part 558 00:18:36,160 --> 00:18:38,960 of two and a half months. Toga's 559 00:18:38,960 --> 00:18:41,039 documentation is the most complex and 560 00:18:41,039 --> 00:18:43,280 expansive documentation within beware. 561 00:18:43,280 --> 00:18:45,440 It has a large API and also includes 562 00:18:45,440 --> 00:18:47,360 tutorials, reference guides, how-to 563 00:18:47,360 --> 00:18:50,240 documents, and topic guides. It required 564 00:18:50,240 --> 00:18:52,400 its own proof of concept. Early in the 565 00:18:52,400 --> 00:18:54,240 overall process, I created a draft PR 566 00:18:54,240 --> 00:18:55,760 showing the full conversion of three of 567 00:18:55,760 --> 00:18:57,360 the most complicated pages within the 568 00:18:57,360 --> 00:19:00,080 API documentation. These pages contained 569 00:19:00,080 --> 00:19:01,760 examples of every element necessary for 570 00:19:01,760 --> 00:19:03,679 the rest of the documentation. Most of 571 00:19:03,679 --> 00:19:04,960 the work that went into this part was 572 00:19:04,960 --> 00:19:06,960 manual as I needed it to be as complete 573 00:19:06,960 --> 00:19:08,559 as possible and I was still working on 574 00:19:08,559 --> 00:19:10,880 building the conversion script. It took 575 00:19:10,880 --> 00:19:12,240 about 3 weeks before I was given the 576 00:19:12,240 --> 00:19:13,840 go-ahhead to officially begin working on 577 00:19:13,840 --> 00:19:16,720 it. As I said, Toga has a significant 578 00:19:16,720 --> 00:19:18,799 amount of API documentation. This would 579 00:19:18,799 --> 00:19:20,960 be our first use of make doc strings. 580 00:19:20,960 --> 00:19:22,240 This was one example of a vast 581 00:19:22,240 --> 00:19:23,679 improvement over the analog sphinx 582 00:19:23,679 --> 00:19:25,840 feature. Make docs make docstrings 583 00:19:25,840 --> 00:19:27,679 resulted in API documentation formatted 584 00:19:27,679 --> 00:19:29,280 differently than the existing, but we 585 00:19:29,280 --> 00:19:31,520 ultimately found it to be better. We 586 00:19:31,520 --> 00:19:33,120 also took the opportunity to do some 587 00:19:33,120 --> 00:19:34,640 additional housekeeping when a literal 588 00:19:34,640 --> 00:19:35,919 port of the old code would have been 589 00:19:35,919 --> 00:19:37,280 more difficult than a new option that 590 00:19:37,280 --> 00:19:39,200 would give us better outcomes. Anyway, 591 00:19:39,200 --> 00:19:40,880 for example, we had tables being built 592 00:19:40,880 --> 00:19:42,720 from CSV files and they're now being 593 00:19:42,720 --> 00:19:45,039 handled by a YAML parser. 594 00:19:45,039 --> 00:19:46,559 One of the concerns heading into this 595 00:19:46,559 --> 00:19:48,000 was that there would be critical things 596 00:19:48,000 --> 00:19:49,760 missed during the migration process that 597 00:19:49,760 --> 00:19:51,200 wouldn't necessarily be caught on 598 00:19:51,200 --> 00:19:53,840 review. This was a major change 599 00:19:53,840 --> 00:19:55,919 involving a lot of files and the only 600 00:19:55,919 --> 00:19:57,280 way we could guarantee everything was 601 00:19:57,280 --> 00:19:59,760 handled was with manual verifications. 602 00:19:59,760 --> 00:20:01,440 To ensure this, I went through the 603 00:20:01,440 --> 00:20:03,039 entirety of the newly rendered 604 00:20:03,039 --> 00:20:04,880 documentation site and compared it to 605 00:20:04,880 --> 00:20:07,280 the previous documentation site page by 606 00:20:07,280 --> 00:20:10,240 page. As expected, this caught a number 607 00:20:10,240 --> 00:20:12,799 of issues and a few edge cases. The 608 00:20:12,799 --> 00:20:14,640 complexity of Toga's documentation meant 609 00:20:14,640 --> 00:20:16,640 this was a required step. With simpler 610 00:20:16,640 --> 00:20:18,160 documentation, it may not be a 611 00:20:18,160 --> 00:20:20,320 requirement. However, doing so across a 612 00:20:20,320 --> 00:20:21,760 simpler setup would take significantly 613 00:20:21,760 --> 00:20:23,520 less time and effort. And especially if 614 00:20:23,520 --> 00:20:25,200 this is your first migration, I highly 615 00:20:25,200 --> 00:20:26,880 recommend it. 616 00:20:26,880 --> 00:20:28,880 Briefcase on the other hand took 3 days 617 00:20:28,880 --> 00:20:31,039 to migrate. This was due to multiple 618 00:20:31,039 --> 00:20:33,520 factors. First, the documentation is 619 00:20:33,520 --> 00:20:35,200 significantly less complicated. There's 620 00:20:35,200 --> 00:20:37,360 less overall documentation and no API 621 00:20:37,360 --> 00:20:39,039 documentation because it's a userfacing 622 00:20:39,039 --> 00:20:41,919 tool, not a library. Second, the hard 623 00:20:41,919 --> 00:20:43,679 work had already been done. Everything 624 00:20:43,679 --> 00:20:45,200 we had built up to this point was more 625 00:20:45,200 --> 00:20:46,640 than sufficient to handle the briefcase 626 00:20:46,640 --> 00:20:49,120 migration, and it just worked. We had a 627 00:20:49,120 --> 00:20:50,960 similar manual audit at the end and 628 00:20:50,960 --> 00:20:53,440 caught very little in terms of issues. 629 00:20:53,440 --> 00:20:55,840 Rubicon Objective C took about 2 weeks. 630 00:20:55,840 --> 00:20:57,200 This increased time was because it 631 00:20:57,200 --> 00:20:59,520 presented new problems to solve. While 632 00:20:59,520 --> 00:21:01,039 the documentation wasn't much more 633 00:21:01,039 --> 00:21:03,120 extensive than briefcase and Rubicon is 634 00:21:03,120 --> 00:21:04,799 Python, the code is written a lot more 635 00:21:04,799 --> 00:21:07,360 like Objective C. This oddness means 636 00:21:07,360 --> 00:21:08,320 treating the source code as 637 00:21:08,320 --> 00:21:10,799 documentation didn't work out so well. 638 00:21:10,799 --> 00:21:12,480 We managed to work around it by using a 639 00:21:12,480 --> 00:21:13,919 typing file which preserves the way the 640 00:21:13,919 --> 00:21:15,760 code is formatted and runs but allows 641 00:21:15,760 --> 00:21:17,440 for presenting the documentation as we 642 00:21:17,440 --> 00:21:20,400 wanted it. Unusual code leads to unusual 643 00:21:20,400 --> 00:21:22,320 complications. The problems we hit 644 00:21:22,320 --> 00:21:23,919 porting Rubicon are not representative 645 00:21:23,919 --> 00:21:25,520 of most problems that most projects will 646 00:21:25,520 --> 00:21:27,440 hit. Most projects are going to be more 647 00:21:27,440 --> 00:21:29,360 like Toga or Briefcase than Rubicon. And 648 00:21:29,360 --> 00:21:30,880 projects that hit complications like we 649 00:21:30,880 --> 00:21:32,480 did in Rubicon are going to hit their 650 00:21:32,480 --> 00:21:34,080 own unique complications because they're 651 00:21:34,080 --> 00:21:35,520 also doing something weird with the 652 00:21:35,520 --> 00:21:37,840 Python language. 653 00:21:37,840 --> 00:21:39,840 That left the website, the migration of 654 00:21:39,840 --> 00:21:42,880 which would take over three months. 655 00:21:42,880 --> 00:21:44,880 Make docs is a documentation building 656 00:21:44,880 --> 00:21:47,200 tool. A website is ostensibly 657 00:21:47,200 --> 00:21:48,720 documentation but with a more 658 00:21:48,720 --> 00:21:50,880 promotional focus. We wanted to maintain 659 00:21:50,880 --> 00:21:52,480 the general layout and content of the 660 00:21:52,480 --> 00:21:54,480 existing site. This meant essentially 661 00:21:54,480 --> 00:21:56,000 building it from scratch in markdown 662 00:21:56,000 --> 00:21:57,520 which is what made this part take the 663 00:21:57,520 --> 00:21:59,679 longest. It stretched the capabilities 664 00:21:59,679 --> 00:22:01,760 of make docs but ultimately I was able 665 00:22:01,760 --> 00:22:04,640 to build successfully build the site. 666 00:22:04,640 --> 00:22:06,320 Content creation with lecter had its 667 00:22:06,320 --> 00:22:08,720 issues. We added some utilities to 668 00:22:08,720 --> 00:22:10,559 simplify content creation which have 669 00:22:10,559 --> 00:22:11,760 significantly improved the experience 670 00:22:11,760 --> 00:22:14,320 for the team. Once this was landed 671 00:22:14,320 --> 00:22:16,080 beware was using make docs across all 672 00:22:16,080 --> 00:22:17,919 projects. This meant the look and feel 673 00:22:17,919 --> 00:22:19,520 of the Beware website and project 674 00:22:19,520 --> 00:22:21,520 documentation was unified which vastly 675 00:22:21,520 --> 00:22:23,919 improved the user experience. 676 00:22:23,919 --> 00:22:25,760 The Beware project also had a series of 677 00:22:25,760 --> 00:22:27,120 standalone documents that were in 678 00:22:27,120 --> 00:22:28,880 restructured text. We addressed these 679 00:22:28,880 --> 00:22:31,360 throughout the migration process. We 680 00:22:31,360 --> 00:22:33,120 automatically generate release notes 681 00:22:33,120 --> 00:22:35,120 from change notes included with every PR 682 00:22:35,120 --> 00:22:37,440 submitted to specific repositories. 683 00:22:37,440 --> 00:22:39,440 Migrating this process meant involving 684 00:22:39,440 --> 00:22:41,120 converting the exist involved converting 685 00:22:41,120 --> 00:22:42,720 the existing documents to markdown and 686 00:22:42,720 --> 00:22:45,200 updating the CI configuration to match. 687 00:22:45,200 --> 00:22:46,640 The most difficult thing to overcome 688 00:22:46,640 --> 00:22:48,320 here is the muscle memory of some of the 689 00:22:48,320 --> 00:22:50,400 team because rest change notes still 690 00:22:50,400 --> 00:22:53,280 show up from time to time. Briefcase as 691 00:22:53,280 --> 00:22:54,559 a project has a number of child 692 00:22:54,559 --> 00:22:56,640 repositories that contain rest that are 693 00:22:56,640 --> 00:22:58,080 templates that produce readmes which 694 00:22:58,080 --> 00:23:00,960 required updating. Every project also 695 00:23:00,960 --> 00:23:02,559 had a readme that was in the project 696 00:23:02,559 --> 00:23:04,240 route that was in rest. These were 697 00:23:04,240 --> 00:23:05,919 updatable by using a simple pandock 698 00:23:05,919 --> 00:23:07,200 conversion and were very straightforward 699 00:23:07,200 --> 00:23:09,120 to verify. 700 00:23:09,120 --> 00:23:10,960 It's easy to look at this as a purely 701 00:23:10,960 --> 00:23:12,640 technical change of a markup language 702 00:23:12,640 --> 00:23:15,039 from A to B. But that's not the whole 703 00:23:15,039 --> 00:23:17,679 story. It's also a social change because 704 00:23:17,679 --> 00:23:19,600 with any project involving a team, there 705 00:23:19,600 --> 00:23:22,000 is also a human element to contend with. 706 00:23:22,000 --> 00:23:24,159 At the time that I started, I wasn't a 707 00:23:24,159 --> 00:23:25,679 member of the core team and I was in 708 00:23:25,679 --> 00:23:28,400 fact a relatively new contributor. I had 709 00:23:28,400 --> 00:23:29,840 spent a number number of years as a 710 00:23:29,840 --> 00:23:31,039 technical writer, but I had not worked 711 00:23:31,039 --> 00:23:32,799 on anything I would consider substantive 712 00:23:32,799 --> 00:23:35,039 code. I wanted to shift Bware to 713 00:23:35,039 --> 00:23:37,200 Markdown across the board. The team 714 00:23:37,200 --> 00:23:39,039 wasn't so convinced. We had something 715 00:23:39,039 --> 00:23:42,080 that worked. Why change? This meant 716 00:23:42,080 --> 00:23:43,840 putting together a proposal solid enough 717 00:23:43,840 --> 00:23:45,520 to convince even the most recalcitrant 718 00:23:45,520 --> 00:23:48,000 member of the core team. I had to be 719 00:23:48,000 --> 00:23:49,840 prepared to address a continuing series 720 00:23:49,840 --> 00:23:52,080 of questions and concerns. This was not 721 00:23:52,080 --> 00:23:53,760 a singlestep process. Rather, it was an 722 00:23:53,760 --> 00:23:55,440 ongoing discussion throughout. 723 00:23:55,440 --> 00:23:57,280 Presenting a successful proposal meant 724 00:23:57,280 --> 00:23:58,720 being able to show the project was 725 00:23:58,720 --> 00:24:00,720 viable and that the results would be at 726 00:24:00,720 --> 00:24:03,520 the very least the same, if not better. 727 00:24:03,520 --> 00:24:05,200 Proving it was viable meant that it was 728 00:24:05,200 --> 00:24:07,679 deliverable, which goes way beyond can 729 00:24:07,679 --> 00:24:09,919 it be done to can it actually be 730 00:24:09,919 --> 00:24:11,600 delivered. 731 00:24:11,600 --> 00:24:13,440 Something being doable simply means an 732 00:24:13,440 --> 00:24:15,760 end state exists. Deliverable means 733 00:24:15,760 --> 00:24:17,440 there is a path to successfully get to 734 00:24:17,440 --> 00:24:18,799 that end state within the given 735 00:24:18,799 --> 00:24:21,200 parameters. In this case, that meant 736 00:24:21,200 --> 00:24:22,799 being able to land this without a single 737 00:24:22,799 --> 00:24:25,840 behemoth PR. Don't get me wrong, there 738 00:24:25,840 --> 00:24:27,679 were several monster PRs necessary 739 00:24:27,679 --> 00:24:29,919 throughout this process. But overall, 740 00:24:29,919 --> 00:24:31,520 each step was kept as manageable as 741 00:24:31,520 --> 00:24:33,600 possible and sufficiently self-contained 742 00:24:33,600 --> 00:24:35,039 that if I needed to step away for 743 00:24:35,039 --> 00:24:36,320 whatever reason, the project wouldn't 744 00:24:36,320 --> 00:24:38,720 fall apart. I was the primary developer 745 00:24:38,720 --> 00:24:40,159 on the migration and there is always a 746 00:24:40,159 --> 00:24:41,679 risk in open source that volunteers 747 00:24:41,679 --> 00:24:43,120 become otherwise occupied and projects 748 00:24:43,120 --> 00:24:45,039 are left unfinished. 749 00:24:45,039 --> 00:24:47,120 To that end, I proposed the process in 750 00:24:47,120 --> 00:24:49,120 stages. Each stage built on the 751 00:24:49,120 --> 00:24:51,039 previous. There were multiple changes to 752 00:24:51,039 --> 00:24:52,320 multiple projects which could be done 753 00:24:52,320 --> 00:24:54,799 piece by piece. We could opt out of any 754 00:24:54,799 --> 00:24:56,640 piece at any time without negating all 755 00:24:56,640 --> 00:24:59,279 the previous changes. This enabled me to 756 00:24:59,279 --> 00:25:00,960 present this as a series of incremental 757 00:25:00,960 --> 00:25:02,559 changes instead of an all or nothing 758 00:25:02,559 --> 00:25:05,120 situation. In this case, incremental 759 00:25:05,120 --> 00:25:06,640 completion meant the inherent risk of me 760 00:25:06,640 --> 00:25:07,840 stepping away was significantly 761 00:25:07,840 --> 00:25:09,840 diminished. But the team wasn't the only 762 00:25:09,840 --> 00:25:12,000 human element. When it came to our 763 00:25:12,000 --> 00:25:13,600 readmes, we took the time to create 764 00:25:13,600 --> 00:25:15,520 labeled good first issues on every 765 00:25:15,520 --> 00:25:17,520 single repository with details on how to 766 00:25:17,520 --> 00:25:19,360 convert them. It took a bit of work up 767 00:25:19,360 --> 00:25:20,799 front to create the issues, but it gave 768 00:25:20,799 --> 00:25:22,400 us an opportunity to engage with the 769 00:25:22,400 --> 00:25:24,559 community. And we were successful. 770 00:25:24,559 --> 00:25:26,400 Almost all of this content was converted 771 00:25:26,400 --> 00:25:30,080 by members of our community. So, how 772 00:25:30,080 --> 00:25:32,000 long did it take? The primary 773 00:25:32,000 --> 00:25:33,520 documentation infrastructure migration 774 00:25:33,520 --> 00:25:35,200 from inception to completion took over 775 00:25:35,200 --> 00:25:38,480 nine months. To be clear, our process 776 00:25:38,480 --> 00:25:40,240 involved one developer. This is an 777 00:25:40,240 --> 00:25:41,679 implementation detail, not a 778 00:25:41,679 --> 00:25:43,440 requirement. This process could easily 779 00:25:43,440 --> 00:25:44,880 have been split up amongst multiple 780 00:25:44,880 --> 00:25:46,320 people and performed in parallel, 781 00:25:46,320 --> 00:25:48,159 significant reduc significantly reducing 782 00:25:48,159 --> 00:25:50,720 the total time needed to complete it. 783 00:25:50,720 --> 00:25:52,159 What does nine months of work look like 784 00:25:52,159 --> 00:25:54,080 in numbers? 785 00:25:54,080 --> 00:25:57,440 37 PRs, nearly 3,000 files modified, 786 00:25:57,440 --> 00:25:59,360 nearly 400,000 lines added, and just 787 00:25:59,360 --> 00:26:01,760 over 300,000 lines deleted. That's a 788 00:26:01,760 --> 00:26:03,840 total of nearly 700 thou,000 lines 789 00:26:03,840 --> 00:26:07,039 touched, an overall net of 83,000 added. 790 00:26:07,039 --> 00:26:09,120 This is probably a bit low, uh, but at 791 00:26:09,120 --> 00:26:12,480 least gives an idea. Was it worth it? 792 00:26:12,480 --> 00:26:14,480 Absolutely. We're in a much better 793 00:26:14,480 --> 00:26:16,720 place. Incremental builds are lightning 794 00:26:16,720 --> 00:26:19,279 fast. Types are natively documented. The 795 00:26:19,279 --> 00:26:20,960 increased configurability of the API 796 00:26:20,960 --> 00:26:22,159 documentation was an immense 797 00:26:22,159 --> 00:26:23,760 improvement, including being easier to 798 00:26:23,760 --> 00:26:25,039 read, better laid out, and more 799 00:26:25,039 --> 00:26:27,120 customizable. Everything is in Markdown, 800 00:26:27,120 --> 00:26:28,640 which means the syntax is easier to 801 00:26:28,640 --> 00:26:30,640 consume. The shared content avoids the 802 00:26:30,640 --> 00:26:32,559 previous duplication of content. The 803 00:26:32,559 --> 00:26:34,480 simp simplification of content creation 804 00:26:34,480 --> 00:26:35,919 means we're far more likely to write 805 00:26:35,919 --> 00:26:38,000 updates, and the documentation is now 806 00:26:38,000 --> 00:26:40,400 easier to maintain. 807 00:26:40,400 --> 00:26:42,000 Don't underestimate the amount of time 808 00:26:42,000 --> 00:26:44,159 and effort that went into this. It took 809 00:26:44,159 --> 00:26:46,000 a lot of one developer's time and a 810 00:26:46,000 --> 00:26:47,440 non-trivial amount of review and 811 00:26:47,440 --> 00:26:48,799 feedback from other developers on the 812 00:26:48,799 --> 00:26:51,360 core team to land it. So, would we do it 813 00:26:51,360 --> 00:26:54,559 again? Unequivocally, yes. It is a set 814 00:26:54,559 --> 00:26:56,000 of changes that wouldn't have happened 815 00:26:56,000 --> 00:26:57,919 if I hadn't come along to do it, but 816 00:26:57,919 --> 00:26:59,600 they're absolutely worthwhile and have 817 00:26:59,600 --> 00:27:01,200 resulted in a vastly better developer 818 00:27:01,200 --> 00:27:03,279 experience for everyone involved. This 819 00:27:03,279 --> 00:27:05,039 leads to a more easily crafted user 820 00:27:05,039 --> 00:27:07,520 experience improvements as well. Should 821 00:27:07,520 --> 00:27:10,400 you do it? That's for you to decide. 822 00:27:10,400 --> 00:27:11,919 Markdown is fast becoming the chosen 823 00:27:11,919 --> 00:27:13,919 format in many ecosystems and is often 824 00:27:13,919 --> 00:27:15,279 more approachable than restructured 825 00:27:15,279 --> 00:27:17,440 text. While much of the Python ecosystem 826 00:27:17,440 --> 00:27:19,440 is still using rest and sphinx, markdown 827 00:27:19,440 --> 00:27:20,799 is proving itself to be a viable 828 00:27:20,799 --> 00:27:22,559 alternative. 829 00:27:22,559 --> 00:27:24,000 I want to note that make docs is 830 00:27:24,000 --> 00:27:26,320 currently in a transition period. Make 831 00:27:26,320 --> 00:27:28,320 docs 1x is no longer being maintained 832 00:27:28,320 --> 00:27:29,760 and there but there are other options 833 00:27:29,760 --> 00:27:32,240 available. There's maked docs 2.0 which 834 00:27:32,240 --> 00:27:33,600 is not backwards compatible with maked 835 00:27:33,600 --> 00:27:36,080 docs 1. Proper docs is essentially a 836 00:27:36,080 --> 00:27:38,720 fork aimed at preserving maked docs one. 837 00:27:38,720 --> 00:27:40,799 Zensicle is a groundup rebuild designed 838 00:27:40,799 --> 00:27:42,480 to be a drop-in replacement to the point 839 00:27:42,480 --> 00:27:43,760 of recognizing the make docs 840 00:27:43,760 --> 00:27:45,200 configuration files as they already 841 00:27:45,200 --> 00:27:48,080 exist. The general migration process 842 00:27:48,080 --> 00:27:50,080 from switching from Sphinx uh to proper 843 00:27:50,080 --> 00:27:51,600 docs or Zensicle would closely mirror 844 00:27:51,600 --> 00:27:53,520 what I've talked about today. We're 845 00:27:53,520 --> 00:27:55,039 looking most seriously at Zensle for 846 00:27:55,039 --> 00:27:56,960 beware. All of the work discussed today 847 00:27:56,960 --> 00:27:58,480 would be necessary regardless of the 848 00:27:58,480 --> 00:28:00,480 solution you choose. Hopefully, I've 849 00:28:00,480 --> 00:28:02,480 given you an idea of the size and scope 850 00:28:02,480 --> 00:28:04,000 of what that change might look like for 851 00:28:04,000 --> 00:28:05,679 you and ways to approach it that are 852 00:28:05,679 --> 00:28:08,000 achievable. Here's where you can find me 853 00:28:08,000 --> 00:28:09,520 on the internet. The link at the bottom 854 00:28:09,520 --> 00:28:11,600 goes to my slides and a resource list of 855 00:28:11,600 --> 00:28:12,960 resource links of all the tools and 856 00:28:12,960 --> 00:28:14,799 projects mentioned in this talk. Thank 857 00:28:14,799 --> 00:28:16,469 you. 858 00:28:16,469 --> 00:28:18,489 [applause] 859 00:28:22,720 --> 00:28:24,880 Thank you Katney for your talk. There is 860 00:28:24,880 --> 00:28:26,320 a couple of minutes for questions if 861 00:28:26,320 --> 00:28:27,919 anyone has them and we can run the 862 00:28:27,919 --> 00:28:32,360 microphone around the room. Excellent. 863 00:28:35,520 --> 00:28:37,679 Thank you, Katney. Um, possibly 864 00:28:37,679 --> 00:28:39,679 apologies in advance for this question. 865 00:28:39,679 --> 00:28:41,120 If you were to do it again, what would 866 00:28:41,120 --> 00:28:43,200 you do differently? 867 00:28:43,200 --> 00:28:46,880 So, there were a lot of um first, well, 868 00:28:46,880 --> 00:28:48,960 first of all, 869 00:28:48,960 --> 00:28:50,960 some of the formatting things, some of 870 00:28:50,960 --> 00:28:53,840 the plugins, some of that stuff. Um, I 871 00:28:53,840 --> 00:28:55,120 probably would have chosen different 872 00:28:55,120 --> 00:28:57,840 options um or at least different options 873 00:28:57,840 --> 00:29:00,159 uh earlier in the process. 874 00:29:00,159 --> 00:29:01,919 Um, 875 00:29:01,919 --> 00:29:04,399 there was uh I'm trying to think what it 876 00:29:04,399 --> 00:29:07,279 was. Um, I'm blanking on it. Apologies 877 00:29:07,279 --> 00:29:11,919 accepted. Um, but definitely uh would 878 00:29:11,919 --> 00:29:13,200 probably have done things in a different 879 00:29:13,200 --> 00:29:15,760 order. Um, that would have been a much 880 00:29:15,760 --> 00:29:19,919 more smooth progression. Um, and but 881 00:29:19,919 --> 00:29:21,760 that would have involved having any idea 882 00:29:21,760 --> 00:29:24,159 what was going to happen in this project 883 00:29:24,159 --> 00:29:25,840 and that I didn't have in the beginning. 884 00:29:25,840 --> 00:29:27,919 I had no idea what I was in for and 885 00:29:27,919 --> 00:29:30,399 probably wouldn't have done it if I did. 886 00:29:30,399 --> 00:29:33,120 So, that one uh is more if I had 887 00:29:33,120 --> 00:29:34,480 understood, I would have laid things out 888 00:29:34,480 --> 00:29:37,039 a lot differently and probably um done 889 00:29:37,039 --> 00:29:40,480 it in a much smoother way. But yeah, 890 00:29:40,480 --> 00:29:41,919 that's the best I can remember on how 891 00:29:41,919 --> 00:29:44,240 what I would actually do differently. 892 00:29:44,240 --> 00:29:46,240 [snorts] 893 00:29:46,240 --> 00:29:48,880 Good. Thanks for that. Yeah. Um you were 894 00:29:48,880 --> 00:29:52,720 talking about translations and uh one of 895 00:29:52,720 --> 00:29:55,039 the options was having to store every 896 00:29:55,039 --> 00:29:58,080 single piece of translated text. 897 00:29:58,080 --> 00:30:02,880 Uh what did how does it work now to 898 00:30:02,880 --> 00:30:04,960 store all of those translations? Where 899 00:30:04,960 --> 00:30:07,200 how does how does that structure work? 900 00:30:07,200 --> 00:30:10,000 Like the structure we we built? Yeah. 901 00:30:10,000 --> 00:30:14,320 So, uh, it's built into, um, the the the 902 00:30:14,320 --> 00:30:17,760 build process. And what it does is it 903 00:30:17,760 --> 00:30:21,279 creates a, um, temp directory. It 904 00:30:21,279 --> 00:30:23,440 generates the translated markdown from 905 00:30:23,440 --> 00:30:26,399 the translated PO files, uh, which are 906 00:30:26,399 --> 00:30:28,799 files that have ma pair string pairs 907 00:30:28,799 --> 00:30:30,559 that are the me original message and the 908 00:30:30,559 --> 00:30:33,600 translated message. And then inside that 909 00:30:33,600 --> 00:30:35,200 temp directory runs the rest of the 910 00:30:35,200 --> 00:30:37,520 build process that produces the HTML. 911 00:30:37,520 --> 00:30:40,240 and the HTML is spit out into the actual 912 00:30:40,240 --> 00:30:43,919 directory um instead of uh having the 913 00:30:43,919 --> 00:30:45,520 markdown exist and the temp directory 914 00:30:45,520 --> 00:30:47,600 obviously is immediately deleted. So it 915 00:30:47,600 --> 00:30:49,840 it we don't have to have static markdown 916 00:30:49,840 --> 00:30:51,120 of all the translations and that would 917 00:30:51,120 --> 00:30:53,200 have been impossible for us. We have I 918 00:30:53,200 --> 00:30:57,919 don't know 25 languages. Um so it was it 919 00:30:57,919 --> 00:30:59,200 was basically figuring out how can we 920 00:30:59,200 --> 00:31:00,799 generate this in a way that doesn't 921 00:31:00,799 --> 00:31:02,799 actually maintain all that in one place 922 00:31:02,799 --> 00:31:04,559 and that's how we ended up doing it. If 923 00:31:04,559 --> 00:31:07,200 you um check out the Bware Docs tools 924 00:31:07,200 --> 00:31:09,919 repository, the build tooling is in 925 00:31:09,919 --> 00:31:11,520 there and it and it it's it's actually 926 00:31:11,520 --> 00:31:13,360 not that complex like the actual files. 927 00:31:13,360 --> 00:31:15,440 There's three of them um or four, I 928 00:31:15,440 --> 00:31:17,600 guess. Uh and it it just walks through 929 00:31:17,600 --> 00:31:18,799 different steps, the building the 930 00:31:18,799 --> 00:31:20,720 translations, building the um actual 931 00:31:20,720 --> 00:31:24,080 documentation, etc. Um and it uses uh 932 00:31:24,080 --> 00:31:26,480 both um the translation or the translate 933 00:31:26,480 --> 00:31:27,919 toolkit. There's some tools in there. 934 00:31:27,919 --> 00:31:29,360 And then it uses the make docs build 935 00:31:29,360 --> 00:31:32,080 system. 936 00:31:32,080 --> 00:31:34,799 Um quick question. What languages were 937 00:31:34,799 --> 00:31:36,640 in the translation? I assume English or 938 00:31:36,640 --> 00:31:37,760 were you talking about programming 939 00:31:37,760 --> 00:31:38,480 languages? 940 00:31:38,480 --> 00:31:41,039 Oh, no, no. Languages, uh, English, uh, 941 00:31:41,039 --> 00:31:43,519 French, Spanish, etc. Um, and I'm 942 00:31:43,519 --> 00:31:44,799 honestly I can't list all of them at 943 00:31:44,799 --> 00:31:46,240 this point. We have so many, but yeah. 944 00:31:46,240 --> 00:31:49,401 No, that's what I meant. [snorts] 945 00:31:51,440 --> 00:31:54,000 So, you said that there was about 80,000 946 00:31:54,000 --> 00:31:56,640 lines that were added. What was was that 947 00:31:56,640 --> 00:31:58,640 in the docs or was that the tool chain 948 00:31:58,640 --> 00:32:02,760 or was that 949 00:32:03,519 --> 00:32:04,799 one. 950 00:32:04,799 --> 00:32:05,360 Yes. 951 00:32:05,360 --> 00:32:06,399 So, 952 00:32:06,399 --> 00:32:08,480 the thing about this, yes, it it's it's 953 00:32:08,480 --> 00:32:11,200 very it it kind of shows things, but the 954 00:32:11,200 --> 00:32:14,399 thing I want to point out is that the 955 00:32:14,399 --> 00:32:16,559 lines added were in everything that was 956 00:32:16,559 --> 00:32:18,799 documentation and everything that was 957 00:32:18,799 --> 00:32:22,159 more API actually lost lines. And part 958 00:32:22,159 --> 00:32:24,240 of the stuff that was added, uh, some of 959 00:32:24,240 --> 00:32:25,840 the formatting, for example, tabbed 960 00:32:25,840 --> 00:32:28,960 content. Um, it's it's two slashes with 961 00:32:28,960 --> 00:32:30,799 like a it says tab and then you've got 962 00:32:30,799 --> 00:32:32,240 the title of it. It's got stuff in it 963 00:32:32,240 --> 00:32:35,440 and then two slashes again. The issue is 964 00:32:35,440 --> 00:32:37,919 that with our translation setup, if we 965 00:32:37,919 --> 00:32:40,399 had all that collapsed into one thing, 966 00:32:40,399 --> 00:32:43,200 uh, the weblate, the front end includes 967 00:32:43,200 --> 00:32:46,240 all the all of the um, uh, syntax 968 00:32:46,240 --> 00:32:50,159 formatting. And so we have white space 969 00:32:50,159 --> 00:32:53,120 between a lot of content. And that's 970 00:32:53,120 --> 00:32:55,360 part of what is making some of this have 971 00:32:55,360 --> 00:32:57,360 gained a lot of lines of code is that 972 00:32:57,360 --> 00:32:58,960 there's just extra white space in there 973 00:32:58,960 --> 00:33:01,600 for the translation purposes. Um we did 974 00:33:01,600 --> 00:33:03,279 do the same in the documentation for the 975 00:33:03,279 --> 00:33:05,200 projects as a um precursor. They're not 976 00:33:05,200 --> 00:33:07,279 yet uh translated but eventually will be 977 00:33:07,279 --> 00:33:09,200 and so those did have that as well but 978 00:33:09,200 --> 00:33:10,880 there's a lot more pros in docs tools 979 00:33:10,880 --> 00:33:14,480 the tutorial and the website. Um so 980 00:33:14,480 --> 00:33:16,559 that's how that ended up being uh such a 981 00:33:16,559 --> 00:33:19,840 significant increase there. 982 00:33:19,840 --> 00:33:21,519 Hi K, thank you very much for your 983 00:33:21,519 --> 00:33:23,840 presentation. was really good. Uh so one 984 00:33:23,840 --> 00:33:26,640 quick question, what was hard for a 985 00:33:26,640 --> 00:33:28,720 human [snorts] to verify? Was it the 986 00:33:28,720 --> 00:33:31,200 translation or was it the technical 987 00:33:31,200 --> 00:33:34,399 parts of the APIs and and check if the 988 00:33:34,399 --> 00:33:37,360 the uh let's say that the doc strings 989 00:33:37,360 --> 00:33:39,360 are correct? 990 00:33:39,360 --> 00:33:41,039 Um 991 00:33:41,039 --> 00:33:43,440 I would I would say it was the 992 00:33:43,440 --> 00:33:47,120 translating uh or it was the the um 993 00:33:47,120 --> 00:33:49,279 parsing the translations and that was 994 00:33:49,279 --> 00:33:51,120 because of those malformed rest links. 995 00:33:51,120 --> 00:33:52,480 What would happen is I'd have the 996 00:33:52,480 --> 00:33:54,559 beginning of a proper rest link here and 997 00:33:54,559 --> 00:33:56,399 then four paragraphs later I've got the 998 00:33:56,399 --> 00:33:58,960 end of a proper uh rest link and the 999 00:33:58,960 --> 00:34:00,399 beginning and end of those other two 1000 00:34:00,399 --> 00:34:01,840 were totally messed up and there was a 1001 00:34:01,840 --> 00:34:03,039 bunch in the middle that was messed up. 1002 00:34:03,039 --> 00:34:05,919 So I'd end up with this huge fake link 1003 00:34:05,919 --> 00:34:07,840 and that involved like manually going 1004 00:34:07,840 --> 00:34:09,440 through every single thing and finding 1005 00:34:09,440 --> 00:34:11,839 those which again involves like I have 1006 00:34:11,839 --> 00:34:13,679 to eyeball it. It's not easy to come up 1007 00:34:13,679 --> 00:34:15,919 with. Um and that was probably the 1008 00:34:15,919 --> 00:34:17,200 hardest thing was just going through and 1009 00:34:17,200 --> 00:34:18,560 dealing with with that. We don't even 1010 00:34:18,560 --> 00:34:19,839 know how those got through because there 1011 00:34:19,839 --> 00:34:22,879 were checks on the original setup. Um, 1012 00:34:22,879 --> 00:34:24,320 but that's where yeah, that's definitely 1013 00:34:24,320 --> 00:34:25,760 I think the hardest part that that I 1014 00:34:25,760 --> 00:34:27,760 dealt with. The rest of it was, you 1015 00:34:27,760 --> 00:34:29,200 know, I could incrementally go through 1016 00:34:29,200 --> 00:34:30,480 the rest, but that was the most 1017 00:34:30,480 --> 00:34:32,960 difficult. 1018 00:34:32,960 --> 00:34:34,560 Okay, that's all we've got time for. 1019 00:34:34,560 --> 00:34:36,879 Please thank Katney again for excellent 1020 00:34:36,879 --> 00:34:39,280 speech on documentation. [applause] 1021 00:34:39,280 --> 00:34:44,000 On behalf of the Pyon AU 2026, I'd like 1022 00:34:44,000 --> 00:34:45,520 to prevent present you with our speakers 1023 00:34:45,520 --> 00:34:48,240 gift and hope you enjoy the rest of your 1024 00:34:48,240 --> 00:34:48,800 conference. 1025 00:34:48,800 --> 00:34:50,079 Thank you. 1026 00:34:50,079 --> 00:34:51,520 Thank you everyone. We'll be back in 10 1027 00:34:51,520 --> 00:34:54,520 minutes.