Merken

Documenting your project with MkDocs.

Zitierlink des Filmsegments
Embed Code

Automatisierte Medienanalyse

Beta
Erkannte Entitäten
Sprachtranskript
what
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
Code
Schreiben <Datenverarbeitung>
Vorlesung/Konferenz
Projektive Ebene
Sichtbarkeitsverfahren
Informationsmodellierung
Gebäude <Mathematik>
Systemaufruf
Vorlesung/Konferenz
Projektive Ebene
Computeranimation
Übergang
Inklusion <Mathematik>
Metropolitan area network
Bit
Gebäude <Mathematik>
Projektive Ebene
Quick-Sort
Framework <Informatik>
Computeranimation
Framework <Informatik>
Computeranimation
Binärdaten
Resultante
Bit
Punkt
Dokumentenserver
Rahmenproblem
Division
Machsches Prinzip
Extrempunkt
Datenfluss
Computeranimation
Vorhersagbarkeit
Metropolitan area network
Skript <Programm>
Projektive Ebene
Informationssystem
Sichtbarkeitsverfahren
Metropolitan area network
Demo <Programm>
Zustandsdichte
Rechter Winkel
Polarkoordinaten
Computeranimation
Rechter Winkel
Vorlesung/Konferenz
Projektive Ebene
Installation <Informatik>
Verzeichnisdienst
Computeranimation
Elektronische Publikation
Kategorie <Mathematik>
Einfache Genauigkeit
Elektronische Publikation
Computeranimation
Homepage
Metropolitan area network
Magnettrommelspeicher
Zustandsdichte
Grundsätze ordnungsmäßiger Datenverarbeitung
Konfigurationsraum
Verzeichnisdienst
Demo <Programm>
Web Site
Datensichtgerät
Browser
Mathematisierung
Extrempunkt
Computeranimation
Homepage
Videokonferenz
Hypermedia
Metropolitan area network
Spezialrechner
OISC
Prozess <Informatik>
Verweildauer
E-Mail
Konfigurationsraum
Bildgebendes Verfahren
Demo <Programm>
Soundverarbeitung
Elektronischer Datenaustausch
Elektronische Publikation
Diskrete-Elemente-Methode
Flächeninhalt
Automatische Indexierung
Hypermedia
Eigentliche Abbildung
Public-domain-Software
Elektronische Publikation
Gasströmung
Elektronische Publikation
Menge
Computeranimation
Homepage
Metropolitan area network
Zustandsdichte
Benutzerhandbuch
Zoom
Verzeichnisdienst
Bildgebendes Verfahren
Domain-Name
Vorlesung/Konferenz
Störungstheorie
Elektronische Publikation
Computeranimation
Instantiierung
Homepage
Funktion <Mathematik>
Soundverarbeitung
Prozess <Physik>
Hyperlink
Singularität <Mathematik>
Gebäude <Mathematik>
Regulärer Graph
Quellcode
Elektronische Publikation
Binder <Informatik>
Computeranimation
Homepage
Texteditor
Domain-Name
Zustandsdichte
Standardabweichung
Verschlingung
Hyperlink
Projektive Ebene
Wort <Informatik>
Garbentheorie
Konfigurationsraum
Momentenproblem
Menge
Computeranimation
Portscanner
Metropolitan area network
Diskrete-Elemente-Methode
Vorlesung/Konferenz
Quellcode
Elektronische Publikation
Ordnung <Mathematik>
Konfigurationsraum
Computeranimation
Homepage
Metropolitan area network
Pufferüberlauf
Bootstrap-Aggregation
Default
Computeranimation
Vorlesung/Konferenz
Elektronische Publikation
Konfigurationsraum
Baum <Mathematik>
Computeranimation
Elektronische Publikation
Prozess <Physik>
Unrundheit
Kontextbezogenes System
Elektronische Publikation
Binder <Informatik>
Computeranimation
Homepage
Informationsmodellierung
Dämpfung
Flächeninhalt
Vorlesung/Konferenz
Projektive Ebene
Information
Verzeichnisdienst
Web Site
Server
Elektronische Publikation
Kontextbezogenes System
Elektronische Publikation
Extrempunkt
Computeranimation
Metropolitan area network
Socket
Hypermedia
Skript <Programm>
Zusammenhängender Graph
Versionsverwaltung
Verzeichnisdienst
Bildgebendes Verfahren
Web Site
Projektive Ebene
Computeranimation
Homepage
Web Site
Flächeninhalt
Verzweigendes Programm
Vorlesung/Konferenz
Computeranimation
Homepage
Web Site
Dokumentenserver
Beschreibungssprache
Verzweigendes Programm
Quellcode
Quick-Sort
Computeranimation
Internetworking
Homepage
Integral
Formale Semantik
Sinusfunktion
Metropolitan area network
Diskrete-Elemente-Methode
Verzeichnisdienst
Zustandsdichte
ATM
Information
Softwareentwickler
Funktion <Mathematik>
Klasse <Mathematik>
Dateiformat
Vorlesung/Konferenz
Wort <Informatik>
Elektronische Publikation
Computeranimation
Web Site
Knotenmenge
Fächer <Mathematik>
Konfiguration <Informatik>
Zeichenkette

Metadaten

Formale Metadaten

Titel Documenting your project with MkDocs.
Serientitel EuroPython 2014
Teil 84
Anzahl der Teile 120
Autor Christie, Tom
Lizenz CC-Namensnennung 3.0 Unported:
Sie dürfen das Werk bzw. den Inhalt zu jedem legalen Zweck nutzen, verändern und in unveränderter oder veränderter Form vervielfältigen, verbreiten und öffentlich zugänglich machen, sofern Sie den Namen des Autors/Rechteinhabers in der von ihm festgelegten Weise nennen.
DOI 10.5446/20041
Herausgeber EuroPython
Erscheinungsjahr 2014
Sprache Englisch
Produktionsort Berlin

Inhaltliche Metadaten

Fachgebiet Informatik
Abstract 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.
Schlagwörter EuroPython Conference
EP 2014
EuroPython 2014

Ähnliche Filme

Loading...