Introduction to Sphinx & Read the Docs

Video in TIB AV-Portal: Introduction to Sphinx & Read the Docs

Formal Metadata

Introduction to Sphinx & Read the Docs
Title of Series
Part Number
Number of Parts
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

Content Metadata

Subject Area
This talk will have four parts: Why Write Documentation Semantic Markup Sphinx Read the Docs The beginning of this talk will cover why you should write documentation. Every talk to developers about documentation I feel needs this part, because when you talk about docs people are inherently skeptical. Once people get on board that docs are important, you can cover more interesting concepts. Then we will walk through the concepts around semantic documentation writing. Similar to Semantic HTML, this allows you to mark up your documentation with metadata that gives you a lot more power and flexibility around the display and authoring of documentation. Then we’ll have a basic introduction to Sphinx. This will talk about the power that Sphinx gives you to write documentation, and examples of how to use it. We will also cover the semantic power of Sphinx, playing on the previous section to understand it in practice. Then at last we’ll cover how to host your documentation on Read the Docs. This will make your documentation beautiful with a custom theme, and allow you to host multiple versions and formats of your docs. The talk will include a basic demo of creating a basic documentation project, and getting it hosted on Read the Docs during the talk. All of the software will be running locally, so the demo won’t require an internet connection.
Point (geometry) Classical physics Computer program Existence Implementation Computer file Open source State of matter Decision theory Source code Markup language Electronic program guide Stack (abstract data type) Bookmark (World Wide Web) Wiki Bit rate Term (mathematics) Authorization Endliche Modelltheorie Covering space Email File format Software developer Projective plane Machine code Word Message passing Computer animation Software Telecommunication Right angle Writing Reading (process) Library (computing)
Web page Computer program Functional (mathematics) Greatest element Link (knot theory) Transformation (genetics) Real number Markup language Function (mathematics) Mereology Computer font Disk read-and-write head Semantics (computer science) Graph coloring Power (physics) Web 2.0 Bit rate Hypermedia Internetworking Analogy Touch typing Authorization Theory of relativity Inheritance (object-oriented programming) Information File format Bit Software documentation Flow separation Arithmetic mean Uniform resource locator Word Computer animation Website Right angle Object (grammar) Reading (process) Probability density function
Web page Functional (mathematics) Server (computing) Link (knot theory) Direction (geometry) Real number Sheaf (mathematics) Markup language Set (mathematics) Function (mathematics) Parameter (computer programming) Disk read-and-write head Number Product (business) Power (physics) Neuroinformatik Frequency Goodness of fit Bit rate Computer configuration Internetworking Different (Kate Ryan album) Computer programming Energy level Endliche Modelltheorie Task (computing) Social class Dot product Content (media) Lattice (order) Line (geometry) Machine code System call Entire function Type theory Uniform resource locator Computer animation Personal digital assistant Right angle Table (information) Spacetime Probability density function
Group action Building Context awareness Direction (geometry) Source code Markup language Set (mathematics) Function (mathematics) Mereology Formal language Mathematics Bit rate Hooking Single-precision floating-point format Extension (kinesiology) Social class Scripting language Software developer Electronic mailing list Bit Variable (mathematics) Electronic signature Process (computing) Internet service provider Configuration space Quicksort Writing Directed graph Web page Point (geometry) Functional (mathematics) Game controller Link (knot theory) Computer file Open source Virtual machine Control flow Automatic differentiation Pauli exclusion principle Internetworking Software testing Data structure Compilation album Metropolitan area network Module (mathematics) Graph (mathematics) Gender Projective plane Content (media) Machine code Directory service Word Computer animation Software Integrated development environment Network topology Mixed reality Video game Object (grammar) Table (information)
Web page Server (computing) Computer file Projective plane Fault-tolerant system Web 2.0 Proof theory Word Process (computing) Computer animation Bit rate Meeting/Interview Video game Right angle Condition number
Web page Onlinecommunity Statistics Presentation of a group Randomization Building Open source Multiplication sign View (database) Open set Web 2.0 Internetworking Gastropod shell Rhytidectomy Inheritance (object-oriented programming) Mapping Projective plane Analytic set Machine code Software documentation Proof theory Digital rights management Computer animation Software Website
Service (economics) Open source Link (knot theory) Computer file Real number Multiplication sign Source code Translation (relic) Branch (computer science) Public domain Function (mathematics) Theory Power (physics) Formal language Revision control Internetworking Kinematics Authorization Business model File system Reduction of order Elasticity (physics) Extension (kinesiology) Arm File format Projective plane Machine code Subject indexing Uniform resource locator Word Computer animation Software Website Right angle Local ring
Computer animation Multiplication sign Condition number
1 of the things that we have a few of the and and and and the and the end of the day and is is who the goal of you for coming and so who my why am I standing here wire there no questions at the end of this talk so about 5 years ago helped co-create read the docks and that is probably why most of you know me about 3 years ago in an attempt to build a community around documentation we create our own conference called right adopts which I helped organize and there are no questions because that is how conference talks should be got to this be come up to me at the end of it and ask questions if you like to so we're going to talk about today 1st thing the covers why she documentation is even if you think you already know hopefully of you would like to clarify some points in your mind as to why you should write them and then also give you some ammunition stop the other people about why they should write them that would cover kind the need of the talk which is reStructuredText stinks and redox so why should we already documentation my favorite is a selfish appeal reasoning and how many people here have sat at a command line looking at a piece of code no like get blame not me not me not me not to make right like someone you a year ago is indistinguishable from someone else there OK and so when you actually have something loaded in your brain and your actually in the act of writing code written documentation allows you to kind of say that state in a way that it can be loaded into other people's brains or your brain later this is hugely important because like so much of what we do is read encoded like loading state in your brain in any kind of documentation that we write about the code whether to comments for the 2 of the tutorial and like this really is just super valuable for people they're actually reading and using software as open-source developers we want people to use the code we write I view documentation is marketing from developers to other developers right like magic was something I did have there's no read me 0 chance I use of library rate like who does that was like he has a really or get every go with no read me I would use that software project like yeah but to those who have been raped is a writing documentation writing tutorials writing Getting Started guides are really that the only way for people to really actually use the software you create is open-source developers just developers like nobody wants to write code that nobody uses it it doesn't feel did you have your you know project canceled at work in the biggest use echoed it's is a waste right so we also write code for the people use it is a writing documentation really allows that to happen in which you could better between there's like this whole kind of movement for of towards readme driven development right this this habit of just like starting on projects you get like super deep in the code is kind of like your models like the implementation details and then you kind of get in to finish the project with almost no thought of like the actual public-facing API for the code you just wrote it is said that the beginning of a project and write a simple readme that's like How will users of the software actually interact to the code I'm about to write you'll end up with a much better designed piece of software so that like that kind of public API can actually influence the implementation details below it and so writing documentation before you write code but also really writing down the ideas of why software is written the way it is makes the software better writing a design document actually justifying why you made certain design decisions in your software will make you think more about those design decisions force you'd actually you know clarify the ideas in your mind the and makes you a better writer really lovely she's talk here earlier and where open-source developers literally 100 % of the communication that we do with each other outside of this room is with the written word like e-mails github issues commit messages comments documentation all this is technical writing who here we just added of books of author panel here and that like the idea of writing is a completely separate skill in the idea of writing code and biting documentation that makes you a better writer which makes you a better programmer which makes you a better open-source community member so that's why you should really be writing documentation of Lee that gives you some ideas you can share with other people so it's getting can have 2 more of the technology so this is basically kind of however thing stacks up I'm so when is start with reStructuredText which is 1 of the worst named suffer projects in existence at her home I usually just say honesty it works fine it's an example of light we markup language who here has heard this term before so about 30 or 40 % well remarkably which is a just a kind of a plain text format there used to generate other formats that traditionally the wiki markup is a classic example markdown asciidoc reStructuredText and they work really well programmer tools that's why we really care about them because all these tools we built work the source code that works as plain text files works amazingly well with lightweight markup languages as well get have deaths pull requests all these tools were the same so
the real power reStructuredText end of HTML honestly is semantic meaning so there's no moving about 10 years ago Nacional world toward like semantic HTML yeah In web semantics really is is saying what something is not what it should look like in describing objects as what it is and somebody else can come along and say this is what it should look like this is kind of a classic in a separation of concerns the kind of issue so an example of this right is like don't make issues bold in your HTML you know you should take your HTML and give the Spaniard deliver something and make that an issue so this allows you the author to seperate what something is from how it should be displayed In later can come along and write CSS to say all issues should look a certain way another example don't make something font color red right that means nothing as someone reading this I have no idea why something is red when I say something is a warning I know exactly what it is as so this bottom example is reStructuredText for you know this is a warning so the really cool part about this right is it is separated from its format like the bottom part that's reStructuredText can be generated into HTML above it also be generated into a PDF can be generated to a man page is independent of the output for so another thing about semantics reStructuredText give you that gives you this power right here the bottom even say just like I would link to Pepe is looking to an example of something that doesn't have semantic meaning is market are marked down right here it's like check out Pepe but just a link to a URL on the Internet there's nothing about like the object that actually is defined in this marker so say they change the URL for where Papeete lives on a Python web site you know this bottom 1 we have we just go and say hey changed about function to generate a new URL so the 1 we have to go and look for every single you know think there might be a link in might actually have a human look at it or do some kind of transformation rate like there's a programmer concept but it's super important for actually writing software documentation as well semantic markup is super super important in relation to the intent of your words in works across output formats and then you can use that to kind of style things a little bit differently so he's 1 of kind of touch on this because a lot of people talk about you know markdown it's like this amazing thing it is media had better my is just shorthand for rendering HTML it's really not a good tool for writing software documentation reStructuredText text is a little bit more complicated and because of that it's a little bit harder right I'm at that complication is there for a reason there's a part of the design is actually important for that complications
so if you care about the words they're writing you should write them in a way that preserves semantic meaning but you're right in a way that has no semantics but you're just kind of losing information you have in your brain that's not making it into the pages and the documentation they're actually writing so st really get into you know kind of what this actually is and what it looks like it is whitespace sensitive just like Python it's extensible and is powerful slightly awkward and so I think it's really can be useful here that just really show you what this looks like an analog tend to be hard can wrap their head around exactly what I'm talking
about so this is a basic reStructuredText text document here on the left side and on the right side is rendered HTML and a long ways it's very similar down right like we make things bold would make things italics around the real power of reStructuredText is say we 1 had a table of contents right doing this something that doesn't understand what a document as you have to just go and look at all the headings and can generate links yourself right but with reStructuredText we please say add a table of contents in it will automatically create a capital contents knowing everything about what is in a document so that's been incredibly powerful thing right like I see these handwritten down like table contents on the Internet and it just fills me with sorrow exist but this is what computers do right like why is the human doing this thing so reStructuredText it's this kind of mock down the thing that's a little bit different and the main way that is different is that its extendable so the big thing as he does so with that contents directive the is another concept of page level marker that's the thing starts with a line search for 2 periods in space and some other market and it ends at the next uninventive line very similar to Python the so directives are kind of the main example this so you have you know dot dot directive name colon colon and as the contents example previously this is really the main thing right it's basically a function call in your documentation you know that the directive name can be anything you can write your own resist giving you that ability to really like do more problematic tasks inside the documentation this is really where things built on top of reStructuredText adding kind of programming level at concepts into the markup language so ejected example right code-block Python that's the thing minors is the line number option so this output y actually have line numbers and then just invented and good example right like it's pretty simple and this turns into output that is syntax highlighted code example it has line numbers right if we remove the line numbers option for my numbers go away right it's it's pretty pretty simple but and he that good luck to know markdown right like hello but there's no way even like conceptually think about doing that In marked down so the other option that reStructuredText gives you is inline markup this is anything it's included kind of it within the paragraphs and like the contents of the text itself this is mainly use reactors including things inside you making things bold meetings italics or kind of stuff so this just looks like a set of colons with was arbitrary role and then backticks with an arbitrary target so again the pop example here is an example of something like this rate were saying but but something that's called Pat and given an argument of 8 and that's basically just like another type of function call to generate that documentation in this in this case will generate a link to Pepe but really you can do anything right it's it's just Python code on the back of in the background so the great examples of this is um references so here you can see on the top where defining a label for this section and down here were actually referencing that section with the label that we defined and so this is really powerful right this allows you to actually reference documents in a semantic way up from across the entire set of documentation right the way of doing this kind traditional is like just put in a link to a URL that is like the page URL of 1 it will eventually be rendered a nation on a production server is like the Markdown right and were relatively to an HTML page but this works with PDF output for example it's it's much more but you're just telling it what to do and it's doing it for you this is what matters into right like there's having and reference automatically takes kind of the title of the heading so I find that the simplest way
thing about this is you know sfor Python code there's something like a model level that's more similar to page level mark and the something it kind of inside of a class level like a method or something like that that's inline markup is this to a different kind of ways of extending pros in reStructuredText so that's
basically basically you know directives are the main 1 is something called TurboTax roles are basically those little PEP 8 examples that I gave after inside paragraphs and so you can actually that little like preview that I made you can actually go play with it online at rst . and i and j ust other word so these what kind of play around with the syntax of something you can do yeah so now you modesty so then Sphinx takes RST and really makes it into a really amazing documentation tool basics things layout is a comp . 5 which is a Python configuration file I Make file that makes disallows local development a little bit easier than a bunch of restructure text files to build them and you just run make HTML so if you pull down a Python project chances are artifacts things documentation and if you wanna build a stocks locally going to the docks directory run big HTML and you have all of HTML documents in your project trading with Django FIL agenda check out just at the not playing and like I the Django docs Cygnus going to the gender check out on my machine generated smell documentation it's really pretty cool so things the best documentation to I know of have been working on redox rough 5 years and I've looked at a lot of a lot of other documentation tools and they're all pretty much awful hum sphinxes is pretty good it's not amazing because doubly the best tool out there that I know of it was actually created to document Python in about 10 years ago I think they documented the Python language itself or the much perl scripts no like I we need we need a better way of doing this and so they build things to actually document Python itself and then it turned into an open source project at the could then be used you know by mirrors the community to document other pieces of code as well and so I was saying so much I build entire website around it which is what redox is i which we'll get to in a bit but things takes that kind of baseline of and extensible markup language that is restructured text and then add some really cool stuff to it the big thing is the torque tree a table of contents tree and this is the way that things actually add structure to a set of documents right like the of a directory of files there's no way to say you know this when to come 1st the short should come 2nd this one's kind of below that other 1 this is how for example Sphinx generates sidebar navigation and it actually build like the structure and links all the documents together in a hierarchical way and that you know as as a code example just looks like talk tree I with a list of female pages in it cross-referencing as i showed earlier is really really cool reStructuredText has cross-referencing within a single page built-in Sphinx actually gives you cross referencing across an entire project and then there's action extension called that lets you referenced third-party projects in a semantic way as well so far I wanna reference the keyword part of the Python documentation in my docs I just say no reference python with the keyword and so that I want to take me to the reference for keywords in the Python documentation and generate a link in my own documentation no Python moves with fewer references rebuild Maddox it automatically re links to where Python moved its of references to this is super super powerful good-natured back entation way less brittle it would Poland exactly all of the references all the documents from any sinks projects and reference them in a semantic way and I just feel like I'm going to this on the internet some URL it's probably get a break and we also reference documents explicitly not just you know find references to have installed darkened support backing to say no dock support and it will generate a proper reference and for that document and then
things really adds all of these concepts for software you know environment variables objects classes filenames man RFCs pets all these concepts that only makes sense for document software is kind what speaks ads into um the reStructuredText kind of base language and so that's why it's really it's amazing tool for document software they built this entire kind of vocabulary and this markup language that is specifically used for documenting software the other 1 is does syntax highlighting answer pigments is sure most people here familiar um just a syntax highlighting LibraryThing github users edits is pretty much all over the internet and it just gives you syntax highlighting which is nice for your users output the big thing is it it itself is extensible the Sphinx actually has its own set of extensions the do all sorts of really wonderful things and then you can also write your own rates you can hook in to the build process of things and really make it do whatever you want to do you are you can actually test your documentation examples with the doctests runner and so the code snippets new docs in actually verify that they I work in next to properly with the doc test extension artist coverage signatures he which here API modules are which you how much your Python code such covered by a documentation just using a graph is support to the lists all sorts of other stuff in there that really just make your life a lot easier when you're writing documentation and all the doctors the other really really big 1 that's things does that actually allows you to pull docstrings out of your Python code and put them into your documentation to the really interesting thing it does here is it actually allows you to mix and prose content with auto-generated content but a lot of tools like Javadoc for all these other you know language doc just give you kind of a full reference in some kind of relatively ugly HTML output and with the you have no control over other doc actually allows you to enter and to mix in you know your own written words with our documentation generated by of a resource code is is with Django lot right it doesn't get it doesn't have like a huge list of functions in classes and stuff they have you know descriptions and like when you know that contextualization of those functions then the an example that's pulled from the source code and then you know more prose and extend this is just like a much better user experience you users can actually understand a documentation as the reading it rather than is having a huge reference has no context for them he sings a documentation generator its main things it takes a structured text files and turns them into all sorts of other outputs and it has a real lot of really really nice way is to just document software specifically so things was is existing in the world and it's a really really amazing tool and so redox came along and of something that I helped create and it build and host Sphinx documentation and at this point it is kind of the de-facto hosting provider for most Python documentation I we have changes pdfs EPA pugs this request fabric him that all this kind of stuff on those exocrine 48 hours in the gender dash in 2010 it provides a lot of stuff kind of on top of things but it's mostly hosting in building of documentation the
saying that the origin stories actually really interesting and the agenda that is basically a 40 hour coding competition are these to be held every year it hasn't happened a few years I think I'm Charles life for myself and in Bobby grace designer spent 48 hours in this kind of built but the proof of concept for this project we looked around like it's really hard to start condition for Python right like badges that another word you upload is a file of HTML and it is hosted I have get up pages which is basically the same thing except instead of a zip file CP it's you know html over get but it's just static files sitting on a web server and I was running out from jobs there is pulling down my repose every 5 minutes like automatically building the documentation hosting of right like world web
developers like but we have tools to solve these problems rate like we have web books we have of you we have all these tools and so that's really what we did is we use like I
wish Villa commit something to get out it should have a web book that automatically pulls it down and build a documentation every time we updated it shouldn't run every 5 minutes just and it should automatically just pretty much work and so that's that's pretty much what we built we set is super super simple proof of concept was like you know love post request it runs this shell command and habitation obviously and it was open source so the code today is still open source actually and and so fast forwarding today it's been an interesting experiment in open source and kind of community websites I think
we're almost 6 thousand km it's we have a bunch of other kind crazy random stats there and the 1 that's kind of blows my mind as we do 15 million page views a month which is like basically 1 of larger sites on the internet high the and it's kind saying they were just kind of hosting software documentation but this is a lot of software it's written on the Internet I we had this kind this crazy thing that's kind of became a real thing exists on the Internet this is kind of Abu analytics which I always buttons presentation just in the spirit of open source in open stats of vacancy Christmas in there every year like I'm that's kind to cool I We relatively US-centric but in China as the 2nd biggest market we have it's really suffer really is a global phenomenon which is really cool on which they have users from every country in the world it is the site every month which kind of a cool random stat going delete the little map that will analytics give you so why wire be watcher using a what is what is kind of the value of the thing that exists on top of things and the 1 I think a lot of you have seen as the theme but we some really ugly defaulting then we pushed new 1 and then someone said is like the Python world got a facelift overnight like we started or the building all the stocks release projects and managers like magically became pretty and so you might be you might have seen
this being somewhere used by a lot of Python docks and so that's kind of are theme we built for redox other thing we do is
versions are so all year got tags and branches from your version troll can be hosted as documentation right so you just have 1 version of your docs online you actually have every piece of software or every and version the released the documentation is built it hosted so that you know if some these 3 versions behind they're not just totally screwed there's no docs for their version on the internet again + kinetics we have it have bucket so you know you put your code it lets us know we automatically pull down the updates rebuild it to documentation is always up to date I we'd actually recently added marked support while I have railed on down I have a lot in this talk i is actually useful for some things like if you're not referencing your source code a lot is riding prose with you know links to other websites it actually works really well c actually do that now and read the redox arm to 7 RST Oromocto died in the a file extension we do do translations Satan actually um things will generate added text output the can use with like Transifex a anything else like this and it actually was to translate your docs which is cool localization is well redox authorities localized into 10 different languages so if you go to the site in China it's actually presented in Chinese which chemical what city there so must be that the real number as search we Elastic Search for everything but it's amazing so we actually index every document we have it we host to search across all of them we use the name so lots of people use reduction you probably don't know just as they're honest over domain like fabric for example uses and last but they have it on their own domain we generate all these multiple formats automatically on every push the PDFs knowing that stuff your docs and we host everything in a reasonable way I think we've never had substantial documentation hosting downtime because pretty much everything is served directly from engine acts so we never actually have Python code running in serving documentation we decide this crazy nest of links that exist on the file system have to support that but that's pretty much always there was incredibly important for infrastructure services it's like in this room would be very upset with me if it went down right now what hit um the there's lots of little small things yeah like Bill failure e-mails you know a Python 3 support have I install your requirements you virtual and all I can he is a redox it's pretty easy you register for an account you give us a URL that has things documentation it and you know you that build we pull it out we build and we hosted and it all pretty much just works uh in theory most the time just works so holiday have have convinced you are at least give nuisance some moreover thoughts on why you should be writing documentation for software and public understand why reStructuredText is kind of walk like wonky and looks a lot crazier than mark down when you actually a right it but there's a lot of power that's there and it's there for a reason end of leaves kind why people using redox and so that is an open source project is still predominantly developed by a very small team of people so this something here interesting and please come help us you know patriotic it have issues you know helped right docs really whatever you're interested in doing and you get a large company that wants to get back to open-source were always looking for sponsors and we're trying to do some kind of sustainable business model around private hosting as well so this is something you've always wanted at your company that we host for you have detected private word now trying to do that is a business as well it so
I like to finish this talk with what looked really shows and the value of that condition me the most and I think it's been referenced a couple times here at the conference but it's you I can't say I'm self taught I've been taught by the people who wrote the documentation thank you and that might be hard for the and