 Felly, ar gyfer ffwrdd ynddo hwyl. Felly mae'n gweld Michael Dugald ac yn yw'r Rydhau Rhaiddedd. Felly mae'n gweld Rhaiddedd yn ddylch ei wir datgu pa'r ffwrdd. Felly mae yna, wedi gweld e wedi'i Twlffedd Fawr. Rydyn ni'n Flasgw, doedd ein bod y Gweithiau Llyfrgellau Gweithgon. Felly byddai'n ymhau bod gennym am eu fforddon. Hydiwch chi'n ff Beth yw'n fynd i'r parflennu mwyaf. Rwy'n gweithio am gynhyrch yng Nghymru. Mae un o'r peth i gael i'w fydd click ac за dwych gynhyrchu'r andio絵or ystyf yn fion ac mae genud i chaosio MG Docs ac MG Docs – mae bod eu bethy言los iawn o'i MG Docs – cazw CL規' i ddaoddi ruins. Y pellaf hwy nad ydych yn cei coincidence er amser. Y rhan oherwydd y j English ac y cadr oedd gyda y gyfer mai oes a bobl yng nghydwyd anion inni ε Vampar. ac rwyf er mwyn yn ymddangos i'r codiiff arfer, felly, mae'r codiiff yn fawr ar ylleydd ymddangos i gyfnod ymddangos. Mae'r codiiff wedi'u gwrthod ymddangos i'r cyfnod ymddiadau o phirion ar gyfer PY. Ac rydym yn ymddangos i'r cyfrydd Cymru 2012. Dwi'n cael eu ddweud o'r hollwch yn ymddiad, rydyn ni'n rhaid i'w Tom Christie, ymddiad ymddangos i'r hollwch yn gyfrifio'r hollwch yn ymddangos i gyfrifio ar gyfer PY. A yna, y gobeithio bydd yn Thomas bydd y mewn gwirlo ffwyaf ychydig yn gynghor. Daethwn i ysgrifennu i ddigon i unrhyw lleol. Dydynt eich hoffi sydd am rhaid i gweithio gyda'u gofyn o'r amser yng Nghymru. Ond ddim yn oes gofynol maen nhw wedi'i amdano ar gyfer felly sefydlu Llaiff, peir i'r cymorth Genisell OCD. Rwy'n wedi gweld oed-dweithio i gweithio'r oed-dweithio. Roeddwn i'r hoffi am roi'n cael ei dweud ysgrifennu? I did consider breaking the build today to see if I could get more contributors, but couldn't quite permit myself to do it. So thinking about the project and the goals, they're quite simple really what we're trying to do I think. And the reason for that is I really want the project to be something that's easy for everyone to use and really simple to use. So it's really about making writing good documentation easier and focusing on high quality prose based documentation. So I'm not really interested in being able to automatically generate the documentation based on code comments. And one of the things that people mistake about me when they hear I work in this project, they assume that I'm probably good at writing documentation. But actually I'm probably just as bad a documentation writer as your average person. So this is really, it's almost like the ultimate procrastination of avoiding writing documentation. I'm writing a tool for writing documentation. But I want to make it as easy as I can for myself and everyone else, and I'm trying to improve as well as I go. So to sort of explain what I mean by high quality prose documentation, I'm thinking of projects like Django, or I think maybe jQuery or Bootstrap to think of non-pipern ones, where they treat their documentation in the same way they treat their code. They're really focusing on sort of crafting it and looking after it. It's not something that's just generated or an afterthought, it's sort of on par with code I think. And some of these projects probably have API generated documentation as well, but that's very much kind of a side of the documentation. So you have your main part and then it's like you can go to the API reference if you want afterwards, which can definitely be useful in some cases. And we've sort of grown quite a lot in the last year. It's actually really a reasonably popular project now. I just sort of plucked four of the larger projects based on popularity. So this is based on things like how big their documentation is and how popular they are on GitHub and stuff like that. The first one is obvious because Tom wrote this project originally. GlusterFS is also... GlusterFS is a distributed networking file system and they just have a really large set of documentation like I think in the hundreds of markdown files. So it's just quite nice to see that it works so well for such a large project than the Docker Python client. And finally, Facebook's OS Query, which is something to do with... It's like a query language for finding stuff about your operating system, which is actually quite interesting. We get a lot of users coming from ReadTheDocs. So many of you will know ReadTheDocs.org, but a lot of people don't know as they support... Sorry, a lot of people know they support Sphinx projects, but they also support MkDocs projects. So yeah, you find a lot of people wanting to use ReadTheDocs from different communities because out of these, I think only... Sorry, two of them are Python and two aren't. We get a lot of people wanting to use ReadTheDocs, but they don't want to learn Python tools and they don't want to learn restructured text. And I kind of overlapped with the slides slightly. What I'm really interested in is making good documentation tools for everyone. It could be for developers or just general technical writers. It's not necessarily about just the Python crowd. I want it to be something that's really open to everyone and it's just really keeping things simple and easy to use. So for example, if you have a git repository of markdown files and nothing else in there at all, you can actually tell ReadTheDocs to build that. They will generate sort of a stub config file on the go and do a couple of settings that they require for their building, but otherwise it will just work and it will just render it fine. And it's just you can't really make it much easier than that. So when you actually generate your documentation, this is what it might look like. Sorry about the screenshot quality. I also figure out this is when I need my pointer. Right. So this is the default theme for MkDocs and this is just a bootstrap-based theme, but it shows a few couple of interesting things, which you won't be able to read, but I can point them out. So obviously this is your main text body in the middle here. And then over on the left you've got the table of contents along the top, which obviously reflects the current page. The navigation on the top is based on the files that you've got in your documentation. And then we've got a search up here, which uses lunar.js, which is a front-end search engine, a JavaScript one, and then just back-and-forward pages. So we've got quite a lot of features, which you get for free essentially when using MkDocs. And then you can see the same thing again. This is our ReadTheDocs theme. So if you've seen MkDocs projects on ReadTheDocs, you might have seen some and not realised because it looks very like this things theme. There are a couple of tales that you know them well, but it's quite subtle. The biggest one is at the very bottom where it says, built with MkDocs. And this is probably our most popular theme. The one thing to note is if you are building on ReadTheDocs, they currently don't let you use any other themes than this one at the moment, just because there's some integration contract we need to establish. And it's a bit tricky for custom themes to do that, so if you want to get started with it, the current prerequisites are that you need PIP and Python installed, obviously. At some point I would like to change that because as I say, I want to reach beyond the Python community. So it would be nice to have installers for Windows and Mac. I'm aware of people doing packaging for Fedora and Debian. The Fedora one looks like it's coming along quite well. I think the Debian one's already out of date as it happens with packaging. But yeah, at some point it would be nice to do some official distributions in that way to reach more people because we do have a lot of people that are struggling on Windows and so on. And it's also quite painful for me to support them in setting up manually. Right, and now I'm just going to try and tawn in the demo gods and do a demo. Oh, that didn't exit at all. There we go. Right, okay, so what I've got here is I've got an empty Git repository. The reason for being a Git repository will be apparent in a minute. I'm just going to make a virtual amp. This is where the internet needs to hold up very briefly. Okay, and once more. Okay, thanks, Cassius. Right, and in this slide, you've seen I've done mpa.new, so I'm just going to turn this into a... Oops, that's weird. Okay, mpa.new. And I don't actually need to do the directory name because I want to do it here, so I'm just going to do dot. I'm just going to do dot dot dot dot dot dot dot dot dot dot dot dot dot dot dot dot dot dot dot dot dot. I'm just going to do directory name because I want to do it here, so I'm just going to do dot. And that's added a base contract file and just it's created a docs directory with one index edit. Now, these are very simple files. The last subline text. Okay, it's just going to float. And unfortunately, I can't see this very easily. So that's the... It just defines the name, which is huge. And then there's a one markdown file there, which is also huge. Thankfully, you should all be able to read that at least. Okay. And now, at this point, as I had in the slide, you can just do mk.serve and this will just work now locally. There we go. Sorry, I had these windows all laid out before and they've moved, which is infuriating. Right. I do know how to use them most of the time. Right, well anyway, you can roughly see what I'm doing. The point I want to make here is the mk.serve reloads. We also use WebSockets, so it will refresh the browser automatically as you go. So when I just do testing title, and you should see that the commands on the left will just go. And it's a really nice experience when you're editing. It's very tricky, apparently, like this, but when you've got a reasonably sized monitor, having them side by side and you're working, it's a release of a slick process. Okay. It's also worth noting that I don't like none. Okay, and then when you're adding new files, they will just be automatically picked up and then automatically reloading and added to the navigation. But because that's too small, it's gone into the bar mode, which is a little silly, but there you go. It's already been added there. And that will keep happening if you've got a nested directory, so it will create a drop-down menu and so on. And then you can see sort of search working here, so which is quite nice. It works really well. It's really fast because it's all done locally. And then the one final thing I want to do, because it's quite nice to see, that I can get back to this, is the experience of changing the theme because that works really well with the library load. So this is my config file. I'm just changing it to use the rededuct theme and it reloads and it just changes and it keeps where you are on the page. And it's just quite nice. It feels really satisfying when you're trying out different themes. So we need more themes just so I can do that more. And then finally, to just sort of finish off the full example workflow of how easy these things can be. And this is why I called a Git repository, which is on GitHub that it was empty. So I can just do mkdocs, GitHub, deploy and it takes a little moment. And now this documentation should be live on here. If I can get that one. Oh, okay. How far that's missing. You can just trust me that it's live. I can show any skeptics at the end. And we'll go back to the presentation. Okay. So that's just kind of showing the full workflow of how you use it in a very simple setup. And it's just this really nice and very easy, this very little that you have to do. But then when you're going a bit further with documentation, you can start to think about how these files would all work together. One of the one of things that's quite common is linking between different sections. And I just got a slide for this because it's definitely confused with some users because basically what you should do is link down file directly. Then during the build process, we update that reference so it goes to the HTML path file instead. And the nice thing about that is when you browse the markdown on GitHub, for example, the links will still work because it goes between the different markdown files. And then when you're linking between different sections, you can use anchors bit which are in all the header tags. And that works really well. But it's also not ideal just when you want to have a change of title of anything because of the detection and warning about if that happens. You've seen the configuration file very briefly when I was attempting to demo. And I didn't really go into much detail there because I thought I'd just focus on it now. But it's basically a YAML file. And again, that's about users shouldn't have to edit a Python file to do configuration for their documentation, at least ideally. And the only actual config option that is required is the site name which is the one you've seen. Everything else but you can change the majority of things like where it loads documentation from, where it builds to what theme it's using, what pages are included, what pages aren't included. But by default it seems reasonably sensible that you would want to include all of your markdown files, for example. So we just add them all and we add them all to the navigation and we index them all in the searching and so on. I then also showed you the deploying. And that was just one of the ways you can deploy very easily with MKDocs because the output is just a static website. The GitHub pages works really well. The Redocs integration is great and they add some extra things on top like they do with Sphinx to do with different versions. So you can have different versions, different builds showing like different branches or tags in your Git repository. And then the Python hosted is also really good. That's the hosting with cheesershop. I won't actually go into the example of that but we have a good example in our documentation. This is something that's actually new in Gitmaster. We've not quite released it yet so it's to do with you can now package up themes and upload them to PyPy so we're starting to get much more distribution there and I'm hoping that once that we're also moving a bunch of our own themes out externally so they can be installed rather than just all included because at the moment I think we've got 17 because we've got a bunch of boot swatch ones which are slightly themed, different bootstrap themes but the maintenance of that is a bit of a pain. So yeah, I'm hoping when this happens we'll then be able to we'll see like an increase in the number of themes available and we'll be able to reuse some of the other ones that people are currently distributing including in their source because that's the only way you can really do a custom theme which is by using the theme directory and providing a local path which is an ideal. Beyond that, I've been on a push for a 1.0 but it's kind of fair to say that I've been doing that for around about six months or so. I initially started and I was like I really wanted to push for it to be as quick as possible but I've stepped back a bit and I'm just trying to carefully add features and then we'll get there when we get there. At the end of the day I could call the current version of 1.0 it doesn't make a huge ton of difference but yeah, the goal is to not add too many more features at the moment where really feel like we're feature complete it's more about polishing things, making things work really well there are a couple of additions that I'm considering trying to get in for 1.0 which is a much better support for internationalisation. At the moment people can use Unicode and write whatever language they want but it gets tricky when you want to support multiple languages and also building multiple versions is something you can do manually but I'd like to just help automate that process for people with some same defaults because it's a fairly common pattern it's something that we struggle with on mkdocs itself that whenever we do a release and then I build a new feature I can't update a documentation with anything else until the new version is released. That actually brings me I think I powered through that really quickly that brings me to the end where I would be happy to take questions about the project or anything else you'd like to know about it and there are some of my contact details if you want to find out more or speak to me later and I'm also hoping to sprint on Saturday as well if anyone wants to join by the way sir, thank you Thank you, I have a lot of questions and maybe additional information Do you have a problem that mkdocs plus mkdocs broke the links Do I have any problem, sorry? In my experience the docs plus mkdocs break the links in HTML Do you have this too? I know that I've noticed I'm not aware of any open bugs about it but I'd be happy to take a look after and help you mkdocs uses Python model that supports only the first version of the markdown no expensive friction You can use extensions they can be defined in the mkdocs config Oh, okay, thanks Can you can you say some can you tell us about some tools that convert doc strings into a proper markdown document because I use right now a doc and it's very, very ugly So in terms of pulling in doc strings into your documentation Yeah So we don't really have any good support for that at the moment it's something I don't think we really want to have that in mkdocs itself What we'd really like to do is do something like that more with a plugin API because it's definitely something that people want there's so many different variations and yeah, if we included something by default there would probably be a python one but we want to try and stay a bit more general so yeah, not really got anything at the moment I'm aware of some people they've got some tools to get the doc strings out which then outputs markdown and then they just build the markdown and it actually looks pretty good I've not had any need for it myself Okay, thanks, and last problem mkdocs supports only two levels of links Not anymore No, that was fixed around a couple of months ago, definitely in the last two releases Yeah, thanks But yeah, that was annoying Do we have more questions? So what would be a major reason for using this over and above Sphinx? For a lot of people it's simply markdown or I think I might be mentioned it just before you're coming in It's fine So a lot of people want to use read the docs for example but they are not from a python background so they don't want to learn python tooling and they don't want to learn restructure text because typically you only know those of your python developer But yeah, for me it's just the real simplicity something that's just that's what really attracts me to it I probably mentioned that but I was a bit like here, so does that just to support like codes highlighting or like if I want to write some Sorry, I didn't quite catch it You know in markdown you can write code, right? Yep But can't you somehow signal the type of the language so it can This isn't included This is called fenced codes so you do like three backticks then you put the name of the language and then you write your code block and then three more backticks and the language is then We definitely need to improve our code highlighting though at the moment it's kind of deferred to the theme so that means people are using using javascript libraries to do it and they're not as good as some of the other tools really No more questions? Okay, thank you Dugo Thanks