 Welcome back everybody. I hope you had a good lunch Well won't won't won't waste any time Tom Christie's going to talk about documenting your project was MK docs Hi there. Thanks for coming today. My name is Tom Christie I'm going to give you a quick rundown today of a little project that I've been working on which is a documentation builder for markdown Calls MK docs or make docs or muck docs. I'm not really sure which yet So here we go. Let's have a little a little look through first of all I want to apologize today if there's any bits of this that are a little bit patchy I've been a little bit busy lately in the last few days. I launched the Kickstarter for project of mine called Django Res Framework Like outrageously Outrageously successful, so I know there are probably some of you who've donated here today. So thank you all of you Anyway on with the show Why why why am I building my docs because it's something that I needed so for when I started working on the release of Django Res Framework 2 I had some very specific ideas about how I wanted the documentation to look And how I wanted it to work and at the time sphinx didn't quite fit in with that The themes are a much much nicer now, but at the time I wasn't happy with any of that and also because Prior to Using my docs I was writing my documentation in RST into blind text And I'm quite a visual person and for me being able to write my documentation in markdown gives me a better flow in some of the nice Markdown editors a better feel of the flow of the documentation For me, I feel like being able to write my documentation with these kinds of tools helps me write better documentation because I can Get more of a feel for how they're going to present to the end users So I really wanted something that was nice and simple and used markdown to generate the documentation so I started hacking away on a little script and At some point decided that I ought to take this hacky little Python script that just lives in the rest framework Repository and turn that into something a bit more reusable and Hopefully be able to use that for some future projects as well and open it up to everybody else to be able to use so This was the end result of how the documentation looked with this hacky little script and My own users were happy with it as well. So that's nice Right. Da-da-da. I want to spend most of this talk Just giving you a very brief demo of using mcdocs just so you can get an idea of What the documentation layout looks like when you're working with it and How simple it is so only a couple of prerequisites Python and pip I would like perhaps at some time in the future to be able to package this up in a way that is Invisible that it uses Python so that we can deliver it to a wider community, but that's something on the long-term roadmap So what do we do to get started? Installing mcdocs from Popeye Create a new project which will Populate the directory with a couple of initial files that we'll look at in a minute and then we're going to start serving our site So let's do that So I already have mcdocs installed here so Okay, so if we take a look down here, we can see that it's written this demo folder and If we go in and have a look and I hope that's just about So there's a inside the directory that it's created. We've got two things we've got a single configuration file, which is a YAML configuration file and we've got a Docs folder with a single markdown file in it, which is our first page of Documentation so that's cd into the directory docs So there we go There we go. This is The the live server that you can run and there we have our documentation Being served locally fine, okay, so what can we do this? One of the nice things that's built into mcdocs is a nice little live reload feature This means any time you alter anything in the configuration or any of the documentation The Site that's being served will be automatically rebuilt and all you have to do is go in and hit refresh in the browser And you can see the effects of your changes So if we go into here, let's just open up the index page Let's change this to mcdocs rocks there's Ryan's There you go nice and easy Do a bit of that as well Okay, so Quick rundown of how the documentation source files are organized Everything goes into a folder called docs It has to have an index md file, which will be the home page You can sling other media in there typically images, but video or you know Whatever else you want in there that you can link to from your documentation And you can also sling in CSS and JavaScript any CSS and JavaScript that you sling in Will automatically get included into your theme without you doing anything else so you can make nice little tweaks to say how the The hero headers get displayed on your leading page and nice little Things like that without having to change the theme wholesale So have a quick look at that Here's a folder where we've got a few more pages of documentation If we just go back to the example that we're working on here what I'm going to do is Add a couple more pages So let's create a You can see I've just added an about and Now I've added a new folder called user guide which also Has a couple more pages in it we go and reload the documentation again You can see we've now got an app bar at the top Has included some extra pages. So here's our about page that we've just added and A couple of other pages and we can Page back and forth between those and all we've had to do was add the new markdown files into the folder in order to add them Similarly with images Just throw them into the docs directory Then you can hyperlink to them from the markdown files exactly as you normally would and they'll be included in the in the output again with CSS and You can also put in other useful things such as for instance this C name file Which is used by the github pages If you want to provide a custom domain and you're hosting your documentation on github pages You can include this little C name file where you just put in the domain name that github should Understand the documentation to be served under so One of the things that Restructured text is very strong at which markdown isn't so strong at is interlinking and obviously interlinking in your Documentation is very important. So how do you do that with mcdocs? Well? The simplest way to link between pages is just to use standards hyperlinks to the documentation to the to the other pages what you do is you Include the hyperlinks as if they're hyperlinks to the markdown source files mcdocs will automatically translate that into the equivalent URL when it's building the documentation or when it's serving the documentation This has quite a nice effect in that when you're working with your documentation in the editors You're able to click on the links and it will automatically end up bringing you up the next page that you're working on Which is quite a nice way to work on it And the other thing that I'm in the process of adding to mcdocs, which isn't quite there is a syntax for a slightly more intelligent interlinking that allows you both to interlink to particular pages, but also to Particular sections of particular pages So there's a simple syntax for doing that which allows you either to just put in a Ref without adding exactly any text that is referenced against and the top link here would Link to a any section it can find in the documents called project license If you don't want the text of the link to match the section that you're linking against you can instead be explicit About the name of the section that you're linking against which is the second one down there That's still in process, but that is that's the idea So configuration Everything goes in the one yaml configuration file It must exist and it has one required setting and everything else is optional so it's nice and simple there's an example there and You can you can use the comfort so with the Example that I've shown you at the moment. We've added some Markdown files, but we haven't specified anything in the configuration for how to order them So it's just automatically decided on an ordering for those you can I won't bother doing it now But you can set up the ordering for your pages by using the configuration file you add a Key called pages and then you just list the order of the source files that you want them to appear in And there you go. Oh, yeah getting ahead of myself So themes, okay There's two different ways that you can theme your documentation There's a there's a whole bunch of Built-in themes that you can use and you can also provide custom themes So of the built-in themes that are available. We've got This fairly kind of bootstrappy style There's also a style based on the really fucking cool read the docs theme that I can't remember who it was who developed it but it's really quite nice and Because the Default style is based on bootstrap as well. There's also a whole stack of Boot swatch based themes available as well, which is really nice and easy to use so for example If we go into our configuration file here, and we say theme United perhaps There we go brand new theme lovely Similarly, if you want to create a completely custom theme of your own you can do that Um Nice and simple the only thing that you need is a base.html file in your theme directory you can Then include any other files that you need and all of the context that gets passed into that templates Is well some of it is documented some of it's in the process of being documented What we don't do is Have anything like particular pages that Only get pulled in particular HTML Pages that only get pulled in for particular markdown source files or anything complicated like that or anything like Partially overriding a theme if you want a new theme either you're using some CSS in your project directory Or you just create a brand new theme Directory with everything from scratch It's just simpler that way around rather than dealing with okay I've got this base theme, but I want to override this bit and that bit Oh Yeah, and here's an example of what a theme directory might look like right so we've got a bunch of HTML files Which will get Translated using ginger to passing in the context Couple of images some fonts styles JavaScript. There you go Okay, so Let's have a look at building the documentation. I'm gonna go and do that now There we go. So you can see building the documentation ends up creating a Folder in there called site which has Which has all of the Final HTML files in there and all of the other media there we go and It builds completely static sites so you can just hope host them from anywhere Most of my documentation I happen to host from get hubpages because it's really good and it's really simple Amazon S3 would work equally well and Maybe one day there might be Integrated support with read the docs perhaps Eric because I've talked about that and said that he'd like that But I just need to find some more time to work on the project first to make that happen So one of the nice things that it also has built in is a nice easy way of deploying your site to Get hubpages So in case you don't already know get up pages is a way for get hub to serve up static pages And what it what it does is? You have to host your site on a branch of the main repo called gh pages and then get hub will expose that on a particular Domain I can't remember exactly what it looks like, but we'll find out in a minute. Oh, yeah, it will look like this So let's go and have a look at the built-in Get hubpages integration all we have to do is mcdocs gh deploy There we go, hang on a minute. I haven't added this site to get hub. Yeah, that would be a good plan. So Here's my empty repository Tom Christie slash demo hasn't got anything in it yet. Let's just push our documentation up to get hub. Okay, that's done. So There's our documentation source up there and Now all we need to do is gh deploy Da-da-da-da-da-da-da-da there so built the documentation and pushes that up to the gh pages branch and Tells you the URL that that should now be available on and Our documentation is live in the internet. Yay Okay Da-da-da-da So I'm trying to keep this super simple I'm not interested in Exposing say a programmatic API to allow developers to override this with Python Really, I just want to keep the overrides based on you can change the theme and that's it This isn't semantic About being a semantic markup tool in the same way that RST can give you lots of extra information about well this word is a class and It means this that or the other. This is just about taking simple markdown files and rendering them into html So it won't easily support Going out into lots of other different formats, but I don't care And Yeah, this is a nice thing as well the wonderful people at Docker Have started using this for their documentation. So I better get my act together And What else yeah stuff it's happening. It's fun. And yeah, that's about all I've got to say. Thank you I'm going to questions So the question was about Uploading the documentation to cheese shop Documentation hosting I didn't know there was such a thing what they host static sites or Oh Okay, new to me set up top pie Upload docs. I'll have a look. Yeah. Oh, that sounds like a sensible option. So No, so that's the question was about Generating API documentation. So I assume you mean inspecting dock strings in Python and automatically now deliberately not actually Really, I'm interested in aiming at pro style documentation I Enjoy reading and writing pro style documentation more than I do Automatically generated API documentation. I'm not a big fan of that style. So Yeah, this is just about textual stuff. Yeah Okay Cool come and say hi. Okay. Thanks everybody