Documenting your project with MkDocs.


Formal Metadata

Documenting your project with MkDocs.
Title of Series
Part Number
Number of Parts
Christie, Tom
CC Attribution 3.0 Unported:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Release Date
Production Place

Content Metadata

Subject Area
Tom Christie - Documenting your project with MkDocs. MkDocs is a new tool for creating documentation from Markdown. The talk will cover: How to write, theme and publish your documentation. The background and motivation for MkDocs. Choosing between MkDocs or Sphinx. ----- This talk will be a practical introduction to MkDocs, a new tool for creating documentation from Markdown: * The background behind MkDocs and the motivation for creating a new documentation tool. * Comparing against Sphinx - what benefits each tool provides. * Getting starting with MkDocs - how to write, theme and publish your documentation. * Under the covers - how MkDocs works, and some asides on a couple of the neat Python libraries that it uses.
EuroPython Conference
EP 2014
EuroPython 2014
Multiplication sign Projective plane Writing
Hidden surface determination Building Computer animation Lecture/Conference Scientific modelling Projective plane Energy level System call Newton's law of universal gravitation
Building Computer animation Projective plane Software framework Bit Software framework Quicksort
Computer animation Multiplication sign Software framework
Point (geometry) Metropolitan area network Dataflow Personal identification number MUD Projective plane Bit Frame problem Variance Inclusion map Pointer (computer programming) Equation of state Computer animation Arithmetic mean Repository (publishing) Uniform resource name Physical law Scripting language Regular expression Normal (geometry) Units of measurement Conditional-access module Arc (geometry) Resultant
Reading (process) Hidden surface determination Computer animation Demo (music) Software framework Denial-of-service attack Right angle Route of administration
Installation art Installation art Computer animation Lecture/Conference Projective plane Right angle Directory service
Web page Computer icon Computer file Demo (music) Directory service Price index Directory service Category of being Computer animation Single-precision floating-point format Configuration space God Newton's law of universal gravitation
Web page Computer file Demo (music) Computer-generated imagery Directory service Web browser Proper map Medical imaging Duality (mathematics) Mathematics Hypermedia Videoconferencing Electronic visual display Website Area Home page Email Building Computer file Open source Sound effect Subject indexing Process (computing) Hypermedia Computer animation Configuration space Website Hill differential equation
Web page Medical imaging Raw image format Benutzerhandbuch Computer animation Computer file Uniform resource name Demo (music) Directory service Units of measurement
Web page Domain name Computer animation Computer file Lecture/Conference Electronic program guide Function (mathematics) Instance (computer science) Perturbation theory
Web page Standard deviation Domain name Building Link (knot theory) Process (computing) Computer file Source code Projective plane Open source Home page Sheaf (mathematics) Hyperlink Sound effect Hypercube Word Regular graph Computer animation Linker (computing) Configuration space Text editor Text editor
Computer animation Touch typing Computer file Moment (mathematics) MIDI Coma Berenices Configuration space Set (mathematics)
Web page Computer animation Computer file Source code Order (biology) Knot Configuration space Ripping Syntaxbaum
Default (computer science) Bootstrap aggregating Computer animation Absolute value Directed graph Default (computer science)
Computer animation Computer file Lecture/Conference Configuration space
Web page Area Context awareness Process (computing) Computer file Information Scientific modelling Computer file Projective plane Directory service Template (C++) Inclusion map Roundness (object) Hypermedia Computer animation Linker (computing) Damping Routing
Context awareness Computer file Server (computing) Building Connectivity (graph theory) Directory service Directory service Medical imaging Computer animation Hypermedia Network socket Revision control Software framework Website Convex hull Scripting language MiniDisc Physical system Library (computing)
Web page Fluid statics Computer animation Personal digital assistant Multiplication sign Disintegration Web page Projective plane Website Website Arc (geometry)
Web page Area Computer animation Lecture/Conference Website Branch (computer science)
Web page Asynchronous Transfer Mode Graphics tablet INTEGRAL Demo (music) Source code Markup language Directory service Price index Branch (computer science) Function (mathematics) Semantics (computer science) Internetworking Object (grammar) Repository (publishing) Website Library (computing) Home page Information Building Software developer Web page Electronic program guide Branch (computer science) Markup language Embedded system Computer animation Repository (publishing) Revision control Software framework Website Quicksort Units of measurement Physical system
Word Computer animation Computer file Lecture/Conference File format Social class
Computer configuration String (computer science) Vertex (graph theory) Website Hand fan
about the writing of getting a bunch of what what what what what was the time time talk about a document your project and talks but things coming today my name's tom
Christine I'm going to give you a quick rundown instead of a project that I've been working on which is the documentation building full model calls and K. dogs all
my dogs all my dogs already show a chair and so here regardless of the level of the
liquid 1st of all I am I want to apologize to diagnose any bits of this there are a little bit patchy by being a little bit busy lately in the last few days I launch the kick start to fall project Michael generates framework which what will right now and maybe just maybe you maybe you have to another probably some of you
terminated here today so thank you all of you wonderful and on show why why why why my building talks because it's something that I need sort of follows when I started
working on the release
of all of our generous framework to I had some very specific ideas about how I want to the documentation to look at how wanted it to work at the times things didn't quite fit in with that of other things are lot of much much nicer now but at the time I wasn't happy with any of that and also the is prior that's to using also I was right my documentation in RST and the blind
texts and I'm quite a visual person for me being able to write my documentation and markdown gives me a better flow in some of the
nicer more than it has a better feel of the flow of the documentation for me I feel like being able to write documentation with these kinds of tools help right better documentation because I can get more more of a feel for how they got represents to the end users and so I really wanted something that was nice and simple and use marked down to generate documentation so I started scratching away on a little script and it's at some point decided that I 2 take this specular Python script that just lives in the rest frame what repository and so and then something a bit more reusable and hopefully be have use that for some future projects as well and open up to everybody else so this is the end result
of how the documentation looked with this practice also and my users are happy with it as well so rights to the
the who way I was the most this told just giving you a very brief demo of using my dogs just so you can get an an
idea of what the documentation layout looks like when you're working with them and so how singular is so only a couple of prerequisites python and take I would like perhaps that sometime in the future to be a package this up in a way that is invisible that uses Python so that we can deliver it to a wider community but that's something on the long-term right now so what we did to get started
installment Duxford owned and creates a new project which will popular directory without a couple of initial possible again in a minute and then we're gonna start something outside of the so already have
moved on since OK so long the also OK so if we take a look down here we can see that is written this down holding and the government and the I hope that just about the so that inside the directory that that's created we've got 2 things with God as a single configuration file which is a young configuration fall and we've got a lot of docs folder with a single mom downfall in which is the 1st page of documentation for the the genes that are truly got there we got this is the the life so that you
can run and there we have all documentation beings of locally finite so what
1 of the nice things that's built into them adopts areas and nice alive reload feature this means anytime you also anything in the configuration or any of the documentation so the a site that's being served will be automatically re belts and all you have to do is going and hit refresh in the browser and you can see the effects of the changes so if we go into here it's just not be indexed by which on change this to there
world the orange they've got the news I should put a dividend that as well happen get so quick rundown of proper documentation softballs all organized and everything goes into a folder called docs it has to have an index star and the file which will be the home page you can sling other media in the typically images but video audio whatever else you want in there that you can link to from your documentation and you can also see in CSS and job strips and CSS and JavaScript that slinging well automatically get included into your feet without you doing anything else so you can make a nice little tweaks to say how the the hero headers get displays on your leading pages nice little things like that without having to change the theme wholesale some have a quick look at that and have and a folder well 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 it add a couple more
pages so let's create and then the data you can just added and about and now I've added a new folder called user guides which also has a couple more pages and then we go and reload the documentation again you can see we've now got enough all of the tall 1 has included some extra pages so here is all about page that we've just added a couple of other pages and we can page back and forth between those and all we had to do was at the new markdown files into the folder all atom similarly with images just throw them into the docks directory then you can hyperlink to them from the
markdown files exactly as you normally would and I'll be included in the in the output again with and you can
also put in other useful things such as for instance on this C 9 file which is used by does it get hot pages if you want to provide a custom domain and you hosting your documentation along get hot pages you can include this little name
fall where you just put in a domain name that get how should understand the documentation to be served under so can 1 of the things that restructured text is very strong acts which markdowns and so strong that it is interlinking and obviously interlinking in your documentation is very important so how do you do that with Maddox well the simplest way to link between pages is just to use our standard Our hyperlinks to the documentation to the to the other pages what you do is you include the hyperlinks as if that hyperlinks to the markdown source files and docs will automatically translate that into the equivalent URL when this building the documentation when of and documentation this has quite a nice effect in that when you're working with your documentation in the editors you are 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 and the other thing that I'm in the process of an intimate docs which isn't quite that is a syntax for slightly more intelligent interlinking that allows you want to interlink to particular pages also to you particular sections or particular pages so that a simple syntax for doing that which allows you to just put a rat without having exactly any text that is referenced against and the top linking here words linked to any section it can
find in the documents called projects license if you don't want the texts of the links to match the section the old linking against you can instead be explicit about the name of the section that you are linking against which is the 2nd 1 down there are that's still in process but that is not the idea the also configuration everything goes in the warm Yemen configuration file so it must exist and that
has 1 required setting and everything else is optional so it's nice and simple there's an example land and you can and you can use the
comforts of with being example that I've shown you at the moment we've added some
downfalls but we haven't specified anything in the configuration for how to alter them so it's just automatically decided on ordering for the others you can and related to I won't bother doing it now but you can and sets up ordering your pages by using the configuration file you adds a key called pages and then you just list the order of the source files that you want them to appear in they got only getting
ahead of myself some of the things um that has 2 different ways that you
convene of documentation that as a as a whole bunch of built-in things that you can use and you can also provides custom things so all of the built-in things that are available we've got this fairly kind of bootstrapping style there is also a stop based on the
roof of the read the docks thing that I can't remember what it was developed at but it's really quite nice and and because the default style placed all bootstrap as well there is also a whole stack all Bruce watch place things available as well which is really nice and
easy to use some for example if we go into configuration file
here and we say being united now again when you
think about the 1 similarly if you if you want so create a completely custom theme of your own you can do that nice and simple the only thing that you need it is based on HTML file annual thing directory you can then include any other falls in needs and all of the context that gets passed into that and 10 plates but it is small some of it is documented some of its in the process of being documented what we've done in 2 areas have anything like particular pages there only get pulled in particular HTML pages on get pulled info particularly more model councils files or anything complicated like that or anything like a partially overriding a theme if you want new thing is that you use links and CSS in your project directory or you just write a brand new themes
directory with everything from scratch it's just simply that way rounds rather than dealing with a guy I've got this basic theme but I want to override this step and that that that if idea and here's an
example of what the directory might look like right so we've got a bunch of HTML files which will get translated using Djindjic so passing in the context of a couple of images components styles John scripts they got this from occurring so so let's have a look at building the documentation and the gun do that now there we go so you can see
the building the documentation ends up creating a folder and they're called sites which has which has all of final HTML files in that and all of the other media you we got and of it builds
completely static sites so you can just hope to post them from anywhere most of my documentation and I happen to post from get pages because it's really good and it's reasonable on Amazon S 3 would work equally well and maybe 1 day there might be integrated support with read the docks perhaps Eric is that it's about and said that you'd like that but I just need to find some more time to work on the project us to make that happen so 1 of the nice things that also has built-in it and nice easy
way deploying your site to get help pages so in case you don't already know get pages is a wasteful get help to serve up static pages and what it
what it does is you have to coastal your sites on a branch of the main areas of colds change pages and then get public sponsors on a particularly to main I can't remember exactly what it looks like but we'll find out in Montpellier will look like this so let's go and have a look at the bill
saying I
get home pages integration all we have to do is exchange deployed of good that we got a minute I haven't added at this site to get up yet that would be compliant so here's my empty repository some Christie flesh damage hasn't got anything in it yet let's just push all documentation up to get that so there's documentation source up there and now we need to do it is judged other than that sort of those the documentation in pushes them up to the GH pages branch and tells you the URL that that should not be available on and all documentations lies in the Internet you few of the uh um to that so so I'm trying to keep a super simple
and I'm not interested in exposing sigh a programmatic API to allow developers to override this with Python really I just wanna keep the overrides based on you can change the femur and that's it this is isn't semantic but about semantic mark-up tool in the same way that RST can give you lots of extra information about well
this word is a class and what it means this that all the other this is just about taking simple markdown files and rendering them into HTML so it 1 easily support going out into lots of all the different formats but I don't care and yet this is a nice thing as well as the wonderful people talking started using this for the documentation so I better get my act together and 1 of yeah so as women it's fun and yeah that's what I will say
Thank you 1 of the questions that you
can do all which the so the question was about uploading the documentation so cheese shop the documentation housing I didn't know there was such a thing what they static sites all of a k mutinies sets up applied public docks other yet that sounds like a sensible option so the each all but not so that's about the question was about generating API documentation so I assume you mean inspecting doc strings in Python and automatic node deliberately not actually really I'm interested in aiming at prose style documentation are and I enjoy reading and writing prose style documentation more than I do automatic fully generated API documentation I'm not a big fan of that style so yeah this is just about textual stuff yeah about what it called comes over but it becomes the river the few


  582 ms - page object


AV-Portal 3.9.2 (c7d7a940c57b22d0bc6d7f70d6f13fde2ef2d4b8)