 Before I begin to talk about anything, so I wanted to like talk about few ideas at the first and then at the same time like do a hands-on session. But hands-on session will depend how many people are new to the things which I'm going to talk about. So I mean how many of you are actually using things right now. Let's just ask one question. So at least, okay, less number of people. So that means we will do the hands-on session. That's nice. So if you want to use or do the hands-on session, please install the Python Finx package. So just search for Python Finx if you are using Mac or if you are using Ubuntu or Fedora or any Linux, just install it. So we will go through things. So I'm going to reuse one presentation which I did last year in 4CNCF. And that's the main line from it. Please remember everyone reads documentation. So if we look at our daily life, we will find the things we use every day, mobile phones, TV, fridge, correct. Few things. Like we go to a new place. We try to figure out how to like, I mean for me when I came to Singapore, I tried to figure out how to use this not vending, actually ticket machines, how to use them. And what is the most common thing in all of them? We read some kind of documentation. It may be manual. Most of the hardware things, it's manual, correct. How to use this new TV, how to use this new phone or this new camera. So that's one point which is very much important that everyone reads documentation one way or other. Why? Because documentation is the communication. That's the most common way to talk to your users. Who are the users? Say you are a company, then that means you are talking about the people who are using your company's product. You are a developer who is creating a library. That means you are talking to the people who are using your library. You are writing an application developer. That means you are talking to the people who are using your application, correct. Yes, no, anything because I'm not getting any feedback and I'm not sure if I'm talking about really stupid things. So please, any feedback. So that's the best of kind of drawing which I can do. Sorry. This is one example I love to show people. The difference between good programs and bad programs. It's one way of quality measurement, correct. Many of you actually saw programs which are actually written by someone else long time back and suddenly one day you went in and you wanted to work on those projects and looking at the code and you have no clue correct what's going on. There's nothing written. You can still find variables like a, b or x and y in many, many big projects if you find out. So that's difficult. So the biggest thing about documentation is who should do documentation. And generally for bigger projects we find there is a documentation team like take any free software project, big ones you will find that there is a documentation team who are doing it. But the idea is about like who should start doing it. So many times it says the people say that documentation is not difficult thing. It's an easy fix kind of stuff or low hanging fruits. But if you think slowly you will find out that the person who wrote that new tool or the person who wrote that new feature is the best person who knows about that feature. So if you expect a new person to come over and start writing documentation about that new feature that may not work so well. So it should be always the developers who should start writing documentation for anything they are working on. They should start writing rather than they don't have to write everything but they should start writing the first level of documentation. And the second point that project contributors that goes into the same way that if you are not a contributor to the project you are not supposed to know about the project and start writing things. You may be fixing the smaller things, say example fixing the grammar or spelling mistakes. But if you want to talk about a feature how great this feature is first you have to understand the project. You have to be a contributor to the project to talk about it. Examples. I am not opening up the sites but I generally show up these three examples. The first project is the Qt framework which has been used to build say on top of it is KDE and the Qt library, the C++ library and the framework. Second project, Django, we know. Third project, MariaDB. So all of these projects one thing is very common. All of them are very much successful. They have a big user base and developer friendly. So what's another common point is that all these projects require, they require along with the code contribution they require the documentation patch too. So Django will not accept your code patch unless you write the required doc changes. I asked one of those Qt developers long time back how come the Qt class documents are so nice, each class examples. They said that if somebody writes a new class, a developer then it's his or her duty to write the whole class documentation. Whatever it can do, the new examples, everything. And it should go into the patch at the same time unless this thing is happening they are not going to accept the patches. So from these three small examples you can if you actually have used already any one of these three things you know what I'm talking about. The kind of good documentation these projects have. So these things are clear examples where people who are developing the things why they should write the code documentation at the same time. How many of you actually read any of the three things documentation, any of the project? You read Django, correct? Anyone else, any of the projects? So Python is again one example. And why? So I'm taking my own example like that's the right hand side is my general handwriting. That's how I try to write. I mean I generally write. And the left hand side is when I try to write a little bit better. So if you get a documentation in both the handwriting which one you want to choose? The left side or the right side? It's a simple thing, correct? You want the better thing which you can actually read and understand. The right side which is my common handwriting and generally the way I write sometimes I get difficult to read that thing. And you want the same thing happen not to happen actually in the way for documentation. Your project documentation should be something which you can clear proper message and people can read and understand. Code comments. So many of my friends also talked about it like what about writing code comments. While doing so they sometimes take you actually both the sides happen sometimes they just write one single line and they think that everyone can imagine or have an access to a machine which can give them the idea of whatever the developer was thinking. Or they write a full paragraph or a full story book inside a code comment. Whatever things was going on in his mind. And this is too big. So I was asking around. So what's going on? Like what kind of code comments you want and what are the things you are looking for. So the first example is the highest used. Like I want to track things. So whatever code that changed if I rewrite a new function I want to keep the old function as a commented code on the top. Then maybe I will not use this code now but maybe after two months or next release or within next week I am going to use this code again. So why not just keep it as a comment. Even I did that many times. Sorry. Like finding code is like oh next time it will be difficult for me to find this part of the code. Let's keep these things. But there is also a question. Whatever to-do entries. So good projects or good code actually keep to-do entries. Sometimes within the code marking them with something like a to-do, capital to-do or sometimes they keep at a separate to-do file. Where they actually explain things step by step. But again coming to the same point that to-do file is also a documentation for the developers or the new people who wants to come and see what are the things left to be done where they can come and work off. Going into details about documentation. So what kind of documentation we see. Tutorials. Tutorials are the small documents which can be read or tried on within say 30 minutes. Not too big, not too small. If you are a library developer or you are writing an API that means you need to have to write your API documentation. Read that documentation and going to learn about your API. Contributor guide. So you want more developers into your project or say you are a company, you are working proprietary code but you still want to hire new people in your company to work on your project after two months or after two years. So you must have a guide which will tell them how to say build up your system, how to do the build system, how to build the whole code, how to test it. So and the last two user documentation we all know and then the how-dos which are like bigger versions of tutorials. Say 2 to 3 hours it will take a time to go through a complete how-to and you will learn a particular part, a particular feature of a project in details. By the way if you have any questions please interrupt me then and there, anything. And people who wants to try this out over their laptop while I am talking please install the Finks project, Python Finks. And Praveen and Ivan also will help us while you are working. So if you need any help you can ask anyone of us. So that means you are using it in a virtual environment or system-wide. Okay then you have access. So what are we are going to do here? Basically two things. One is restructure text. The second part is the Finks project itself. How many of you actually know about restructure text? Or how to write it? Okay 1, 2, 3, 4, 5, 6. So if you remember a presentation a few minutes back, nice blue color on the top and small, I mean the title was written below and it was written using text. So you already saw it a few minutes back. I am going to just show you how can you do that in a fast way. So you can actually use this link or note it down. So later on you may want to have a look at it. So this was created for an online summer training. So this is a fast track for you for restructure text. So we are going to do that first so that it will be easier for us to do the Finks a few minutes later. So you need the docketills package and most probably it will be installed in your computer already. So just to check, please have a look if you have a command called same rst to html. Just figure out just type rst digit to html. This is the command. So please have a look at if you have the command installed on your computer or not. Who are trying this out? So I will know how to check. So do you have it whoever is trying? Yes. So here, do you have it? The people in the back, do you have it? So install the package called docketills. Python docketills, please install. It's not that big of a package. So restructure text is the plain text based on it's a format which is using the plain text to help us write documents and this presentation is also the similar kind using restructure text. So tell me when you are done, ready with this thing. People who are missing docketills. There are few people. So we will go through this restructure text thing a little bit faster because you can always check and I also don't remember all the stuff all the time. There are users who need to find these things out. Please inform me when you are done, ready? Are you ready with docketills? Excuse me. Do you have the restructure text now? So I am not going to use like I am using Vi but you can actually use any editor of your choice. The extension is .rst. So for our example we will create a file called .rst. Use the editor you love. So going to details. So a document can have a document title, correct? So this is one way of writing a title. So I am using the equal to signs. Equal to signs on the top and the below. The requirement is it should be at least the same number of characters or minimum the same number of characters of the main text and top and the bottom line should be the same number equal to signs. Yes. So how can you, because of the countermer that's entirely right title. Oh no, so you have to keep pressing the equal to sign, correct? And if you are using a modern editor like Vi, Emacs, anything they have features to actually add, like plugins to just add it for you or sublime text. So they all come with different plugins. So where you can just type the title and then like press a key combination. There are, like just search. Because these days I'm not actually using any plugins in my Vi. I'm doing it manually. But sublime text has one restricted text snippets or something, that's the sublime text one. Yeah, but that's the minimum number I'm talking about, correct? Yes. The same number of characters, yes. Unicode is always a big issue, correct? Like for most of us in many projects. Yeah. And like time to time I see problems which I have no clue where and why they are coming. So I'm just learning those things, like when and where I'm coming to any particular issue. But I'll keep that in mind. So now we can actually create an HTML out of that restricted text file. So this is the command. RST to HTML. The first the restricted file name and then the output final HTML file. So just click and press enter. You should have the HTML file in your computer and just open it in your browser, favorite browser. Or not so favorite one, but got it? So I'm going to skip things now. I mean a little bit faster. So we can have paragraphs of text in our restricted text. Blank, that means empty line will create a new paragraph. So if you want to write 10 lines in a paragraph, just write them continuously without giving any blank line in between. So empty line will create a new paragraph for you. So just type out something randomly, some characters so that you can find it out. Comments. You can actually have comments within restricted text. I never use them yet. You can still have them if you want. Section titles. So generally, documents can be divided into sections, subsections. So any of those characters can be used as a section title. And the idea is you put the characters below the title. And you can choose any one of them. And say for example, if we choose the dash as a section title, and next time you have to use the dash again, you cannot use any other character for the same level, say section title. So this is an example. Here, we use the section title as equal to. So next, if you want to create a subsection, we just use another character, that is dash. So it becomes a subsection. Yes. So that depends on you, like whatever you want to use. But you have to follow the same thing throughout your document. But I generally never went more than subsection level, like sub-subsection. I never had one. So bullet list. That's the easy way. You can again use any of those characters to create a bullet list. Please try it out if you're typing. Use any of those characters for a bullet list. This is the unordered bullet list. Is there a way to type code? Because you show the output of this text, and the code that we should use in the same format. Yes. So as I said, I don't remember things all the time. So even I would love to see how I actually did that. So this is the RST file which I used to create the presentation. Here you go. So the two colons with a tab, that's how generally we write any code examples within restricted text. And in things also, we are going to use the same. So you can see here, like the RST to HTML, it's with a tab. I mean, in this case, four spaces. And we are using this. It's going back here. Ordered list. You can do two ways. Number one, manually type the order on the numbers. One, two, three, four. Or you can get it automatically. Following this rule. So the topics will take care of number two and number three in the list. So it will add it up. Please try it out if it works. If you have any problem. If you have any problem, just ask so many of us here. We'll help you out. Steven, do you think it would be a good idea then to actually add up a few examples with the unicode text? Do you think it would be a good idea to add examples with the unicode text and showing them the error if they can get it? Because that's maybe a way to improve that. Most of us are still not using many cases. Okay, I'll do that then. So there are other things. We are not going to try these things out, but things like definition list. Example, option list. So things which we use to write down like the command line arguments and how you can pass. Those arguments to your particular executable. Then the literal blocks which we use which we are using right now to show the examples. But as you can see it's not using any kind of syntax highlighting and things which we are going to see in the next, the things when we're going to use things. And we can actually have doc test things. So in things we can actually, you can add up your doc test and you can actually run those doc tests from your project documentation and building the documentation. And you can do that. The last one? Yes. So you know about doc tests, correct? You will write titan in the prescription test. Yeah, as a doc test. And we can actually execute that and we can find out if the tests are passing a fail. So that means two things. Number one, you have tests. Number two, your documentation tests are always the correct example because if they fail you will already know it, correct? So you don't have to be worried that your tests are in a different place and you have to copy them to your documentation. You know for sure that your documentation tests are the right ones and they are running passing right now. So you can have table structures. There are two different ways. You can, if you want to have as, like, simple way or a little bit more complex which is not getting inside here. But both of them will work. And one more common thing is links, hyperlinks. So that's an example of how to create a hyperlink. You may want to write this one because this is there pretty commonly in many documentation, correct? We want to add hyperlinks. You want me to put the fit around? It's very important that people haven't done much with structured tests. The white space is significant. So if you write a double column and want to follow this code you actually have to have a new line out of double column. So same thing with the stuff released. So I'm just saying that properly but you have to give blank lines to mark end of the last section and then you are starting writing something new. And hopefully all of you write Python sometimes and that means you know how difficult not having enough white spaces mean, correct? And thanks for adding that up. So we can have targeted links also. That means we write down the links details one place and the final destination of the link in another part of your document. I'm just going to skip this because it will be easier. And well, this is again, many times we use this. This is the node. Dot dot node double column and then the nodes. And you can have many things inside the node if you want. Emphasis, text between star. Simple to remember. I know you are typing. I don't know. Are you typing these things? Okay. So you are just typing. What you showed before the table, green tables. Yeah. That's fine. We can see it. Yeah, so. Is there a better way? So better way I cannot say but subline text actually, and even VI, I think one of the plugins had a way like you just write plain text and then press some key combination because it will do magic and it will give you the whole structure drawn for you. The problem happens when you actually make changes. You change any text inside that table and then this end and the beginning goes here where completely. You can have footnotes if you are writing, say, for a book or something or an article. I'm just skipping it. Any questions? Anyway, so this is the end of the basic things which we are looking at. Anything to the RSD? So if you have written all these examples, then I can teach you one small thing which is how to write a pre-created presentation. So you have a file, correct? Test.html. Test.rst, the source code which we are writing right now. So you can use another command which is rst2s5. That is, so you don't have to install it. It comes by default with Docutils package. Rst2s5. And use this on the Rst5 or restructured file you just wrote to create a presentation which will look exactly like that one. You don't have to note it down. You can just Google for this. So it contains the whole specification. So if you want to know what all things are there in restructured text, you can just go there and find it out. But just use Rst2s5 to create the presentation and tell me if it works for you. Yes, correct. The style is inside. Yes, so you can actually pass one of the arguments if I remember with a style sheet and it will apply the style sheet. And there are other tools also while we are discussing this. There is another tool called Hovercraft. So Hovercraft, it creates another little bit different kind of presentation. I can show you just an example. So I am going to just skip through the presentation and nothing to talk about the presentation. But this is created using the same Rst. But with a little bit extra formatting. So instead of sections, here we are using four dashes to create a new slide. And you can do 3D also which I never used but it has a little bit better way of things and you can pass the style sheet and things. All this little bit fancy stuff. I know it's just... Yeah, I know if you use it. But this is the time when I was actually learning this tool and I found, okay, let me try out different things. And this is also a restructure text. So by using this way if you create presentation you will spend more time in actually on the content rather than on the look and the feel of the presentation. So I think most of us actually want that part, correct? Focus on the content rather than the way it works. Thank you. So this is that Python Overcraft project. This is the presentation hovercraft.rt80.org or the docks. So have a look later on. You don't have to do it now but just note it down. So can we move to the things? If you have any questions on the restructure text. Any questions on this? Not hovercraft but RST restructure text. We can move into things. So I just created directly 2015. I'm going to use this as my documentation project. So the general idea is when you create a project it can be a project by the way things can be used for many things. It can help you to create your man pages. It can help you to create your book, PDF or it generates PDF using latex most of the time. So the PDF output looks really nice. We'll have a look at it. It can help you to write books. So I know people who wrote music related books using things. I have a very small book on Python programming which is basically about teaching Python to people. I'm going to go to that example first. I mean this is things what you are looking at here right now. So this is how the things output finally looks like. So he wrote the documentation using things. This is a website called readthedocs.org or rtfd.org. So this project automatically generates your project documentation when you make it available somewhere using some kind of version control system. So I'm going to... And you can have different kind of themes. So I'm opening my book which is pymbook.rtfd.org or readthedocs.org. It's called Python for You and Me. Good thing is there are things like I am actually having two different versions. So the latest is the Python 2 version of the book and there is a Python 3 which is basically a grid branch Python 3. So there is a Python 3 version of the whole book and you can download the pdf or html things from it. Okay, coming back to things. So how to start writing documentation using things. So which was supposed to be the main part of the whole workshop. But I think we have 12 minutes for it. So what's the benefit with using this one that we just write in html? No. So if you write html then you have to maintain the html, correct? We just use like like a tool test processing or one of this work and it's used so that we can maintain as far into the PDF. Correct. So there are a few points so you should feel free to actually use that kind of workflow also but that means you're using more than one tool. And here the benefits what I can see all the time is we are using a standard documentation format which is restutter text. The same tool can give me my main pages. The same tool can give me my really good looking documentation in html, single file, multiple files. The same tool can give me my PDF. And there are already so many projects which are using things. The biggest example should be Python.org itself in the documentation section. So if you read Python project documentation or if you have the PDFs in your computer which you downloaded maybe before and you want to read about it so all of those are generated using things itself and because they use a different theme so the documentation look a little bit different. So that also means you can apply your own theme you can create your own theme and we have projects like read the docs like here which takes care of all your yeah. So read the docs.org this project will take care of all your building of your documentation and publishing it so you can actually configure your github or bit bucket so that every time you make a change and push it to your github or bit bucket the project documentation will automatically get re-bent every time for every change. So that means your documentation is always updated the latest thing and if you want you can keep maintaining the older versions also as a documentation so and you don't have to take any headache. Correct? It's running there all the time. So now the documentation itself is in the code that it generates from the code? Not, yeah we can do that also we will see a little bit small example of that also but most of the document will write separately so that it becomes easier for people to understand and I don't know how many of you read PayPayT anyone? No? Okay. So how many of you know about doc strings how many of you are a Python programmer? First, you write Python regularly how many of you? I mean once in three months so how many of you actually know what is a doc string? Okay, doc string? So yeah so I will just go through that example like how you can actually write a little bit better doc string which can give you a way to actually automatically generate the thing the way you want Is this raining? Yes Wow, nice Yeah So the idea is that your documentation generally stays in a directory called docs DOCS all small so I created a directory inside my project I am going inside the docs directory So this is a standardized name which each and every project in generally using and the reader docs also takes that as a default path to find your documentation and so there is a command called things-quickstart please do not press enter listen first there is a command called things-quickstart which is basically few steps it will ask you few questions and based on the answers it will create the make file and the configuration file may not make make file the configuration file basically so you will use that configuration file to generate your documentation so I am going to go through it and you may want to follow along with me so root path for the documentation so this is the docs directory this is where I am going to do it so current directory separate source and build directories I am going for the default option no name prefix I am going with the default option underscore project name this is something I should pass what should be the project name process name author's name I am putting in my name project version 0.1 release it is the same source file suffix so actually you can have either .rst or .txt both of them as the source file for documentation I am going to use the default .rst so that I will be sure that this is a restricted text from the extension master document is the index that means index.rst so now these are the few features which you can use so if you want you can actually rebuild or build EPUBs out of your documentation say you are writing a book instead of just normal documentation so you may want to write create EPUBs I am going to do no actually I am going for no for most of the things the thing you asked for automatically getting documentation doc strings from code I am doing it no for now we can say later on doc test do you want to run the doc test the thing I was basically a few python classes you have to write inside python list in a configuration file write to do entries I am also saying no coverage we can actually add coverage so if you have some kind of mathematical equations there are two ways of generating it one is PNG yeah coverage means that to wariness so it goes into parts of the source code to check that's yes that should be the I think that should be the way or maybe just import the code and see the doc strings are there or not I mean I don't know how it implements it so probably looks at how many functions you have without doc strings and how do you that you should probably keep some in mind so that makes sense without the doc yeah so so there are two ways PNG math you always know if config I am just going for no I never used it yet view code so sometimes you want to give links to like view the code when you are say documenting your API documentation or documenting some class somewhere so now create makefile yes we want to makefile windows command file that is the .bat file I generally put it no because I am not using windows done so after this you just do the files you will see these are the files and directories got created so we have a underscore build this is the place where the final build will happen we have a .bat which is basically all this input which we just provided index.rst is the default index file for your whole documentation makefile and there are static underscore static for any static say in your theme you have some kind of images documentation screenshots or photographs and templates so templates is the place where you are going to use for themes like you want to add particular templates I am going to open up few files here first we are going to see the con.py so you will find out it is a python code which all the thing we put the input we provided the input these things become the parts here so if you want to change your project name you just have to change here so if you remember all the extensions we said I said no to everyone so those extensions are basically here will come here and there are other details so if you are generating some say let's say latex paste pdx or latex output so you can add up extra direct input to the latex system here so like for man pages say your project like which section of the man pages should go for so you can add all those details here and these things are pretty heavily documented into the things website dot if you just have to google once if I open up the index dot rst which are almost out of time but anyway so this is the index dot rst this is the default thing they will give you the things project so you can understand that's the top title there welcome to fosacea the project's name comma I mean documentation and then there is something special here correct dot dot so c3 that is table of content tree so because the documentation for a bigger project will not be only one file it will be spread across various files so we can actually have a table of content directly added here so I'll just write first here and then we'll go through remember this thing this is three spaces by default things creates with three spaces so if you press a tab or create four spaces it will give you an error and it's generally very difficult to find out why it is causing the error for us at least we've figured out like during workshops we'll become little bit confused why so I'm giving just these three spaces so let's say I want in my documentation the first thing I want other than the index maybe install guide correct we need an install guide how to install your software so I'll write the file name without extension install that means what should be my documentation file name install dot rst is it okay? so this name is the file name without the extension in the develop contents is it okay? so now I'm just going to get out and create install dot rst how to install forces here so if I want to have a paragraph like I'm just writing some random documentation so you feel free to add whatever you want to write maybe so this is the install guide this is how you install forces here I'm going to close this and generate the documentation now so there are various builders which are basically what all things you can do with spinks I'm just typing make so it will give you an options what all things you can do if you see it's a pretty long list the things which are available for you we're going to create only the html you see so I'm going to do make html done so it was docs and okay this is the thing make html we got this so the output is underscore build and inside there is html directory I'm going to view the index dot html and we got this so this is the chapter we wrote correct install chapter so you can see the section came here as a section and the subsection is below in the develop content and you can actually know how down you want into the section subsection subsection all those things so I can actually click it I'm here I can see and this is the default theme of spinks so you can feel free to choose whichever spinks theme you want and because this is a static html you just have to publish it over some directory running some web server any web server there are a few things you will get by default with these things like module index you can get index and you can actually search also say here you go so you don't need any particular search engine running on the server to help you out with these things this comes as a default feature and you can remove it also if you don't want any search box you have a question so just try out build your own documentation please ask what's going on so if I open again say install.rst say I want to create a link can you tell me how we did it how we did it anyone remembers how to create a link and then I'm going to make again so now we have a link to the primary website here the best way to learn about things is not actually only about reading the things documentation because it's in depth the easiest option is actually if you want any particular feature which you saw in any other documentation just open the rst file and see how they did it and just copy paste it will work all the time so generally what I tell people like so this is the book which I talked about python for you and me which I showed few minutes back so it contains a docs directory forget about the rest of the directories you can just go to the docs directory and you'll find the whole book as rst files as a things documentation there so if you want any particular things which are there in my book and if you want to have the same thing in your documentation just open up the corresponding file and see how I did it and there is obviously the things the site itself contains all the other documents that means you have to install it outside it's called rst2pdf it's from another python developer ralsina he is from Argentina which is a very nice project if you want to create any quick pdf files from your document so it's just like rst2pdf rst file hyphen old output pdf file but any questions I don't think I will continue too much to mention another feature that I found is extension to use brackets oh ok the hot is not optimal ok I never knew about it because it's graphics where is the graphics those things those other extensions ok nice actually other than doctase auto import I mean from the code things I don't think I used any other extensions till now see this is what I was talking about that you figured out how the other person their file see the example copy paste yes so as I said so the best way to learn is I don't know where I have the example so the best way is so in things you can actually interconnect different projects so you want to go to the module where you have the module example correct or say for example you are writing something a python api and you want to link to the python projects say counter class so there is a shortcut ways which are available inside fields that you can just write it like collections and what do you call the class counter and it will automatically create link to the latest version of that thing so we can have actually look at it a little bit of it I am opening the documentation which I wrote before so that it's easier for me to actually remember I was doing the things I hope this contains some examples yeah so this is the documentation which I am like documenting my api of the submodules so if I go to the docs actually but this is a bad example maybe I am just using this table of contents but I don't remember the exact same text so just Google for it you will find all that it is there and I was actually trying to show something else which is the directives which is starting with dot dot like dot dot note yeah so the directives have specific programmable stuff like dot dot function dot dot method and then you can follow up with either your own so if you manually document your code you have to like function and compare them with but if you do function making back quotes you say where your source code leaves you don't actually find your part your function and it's just a configuration and you have to write functions back quote that means you want to leave this code and another option is actually say do I want to have like expansion click to show source it will embed the source code that you are talking about so what you should do in the code section you are asking me correct so here using the documentation I mean doc string I actually wrote that thing that colon class colon and within back ticks retas.connectionerror so when this documentation will be automatically generated it will know where that class is there so if you click on that it will actually take you to that connection error object so it gets the doc string and if it has the directives there you can use this in your you can use this directly in RST class you can also use that in your doc string so your doc strings can your complete restructured text things so whatever you write there you can actually write it down here and in python documentation which is the thing is that you have to write both places so say you are adding up a new function so you have to write the same documentation quality documentation as your doc string and then you have to write the same thing in python that is the documentation directly also so we maintain both places what I thought about strings was that you could do just put the hope write everything in the doc strings and run strings on the code and get the documentation out of that you can do it like up to a level say you can add up doc strings in the module level strings and you can add many things from there but at the same time you do not want your code to be like 2000 lines when you have say extensive documentation so you want up to some level because the good thing about doc strings like this is that if somebody is actually do not have access to your documentation they are actually imported the module say in the python interpreter and they want to help on the say class or function they will still get this plain text restricted text and they can understand what all things are there so you will see another example here I used a column return column so that way I can actually mark inside a function like what is the return time so and then there is a note and there is a doc test third part so if I see this example this is the q correct so if I go to q this is the thing so you can see that column return column automatically became returns correct exactly what this function is returning and then there is a doc test so and true was evaluated when you generated this object yes yes so you can see from the documentation it's a test effect yes or you can use it at the same time you can use it as an example code also correct that's an example code and it's a test and it's a valid test yeah so your question when you run your build of the docs your doc test will run and you will see an output in HTML of this doc okay so you don't want to publish or maybe you want to fix it before but we always do that correct pushing something which is a failure with it yeah because we're done right test that's a different problem altogether I'm not going into details for that fighting that but the idea is like if you have good documentation you will always find that I mean people will come to your project if they can't find good documentation they will spend maybe few hours maybe few minutes and they'll move to the next project or next company or next product because that's where you do the first level of communication with your users and I'm showing things because I personally found that's a very nice and simple way for me to create better looking good documentation and so many other projects are doing it let's say but there are obviously other tools also available for documentation it's not like you only have to use things like I used to do I mean say you are doing blogging correct and you can actually do blogs using registered text also there are many available options but the best option is from the same guy Ransin who wrote the RHD2 PDF it's called Nikola the website is GetNikola.com this is I think with the highest amount of features and super fancy registered text features it can do YouTube videos galleries and many because they added lots of I mean there are so many options correct I was fun part was like I was using Nikola lot in between because of the upgrades and I did something stupid I had trouble to actually rebuild the things when the little bit syntax configuration file actually got changed so after that I moved to Mangtown based blogs because I figured out in my blog I actually am not doing so much fancy stuff so I just need my blog is running my own tool that maybe you can mess it up one so the nice thing about Sphinx is that it's already an old project with so many plugins that you can do stuff but there's a new project for simpler another upcoming the commutator called MKDocs it's by the same guy who did Jungle Restful so the full Jungle Restful is written in MKDocs a lot of so it already has a built-in read-the-docs theme which is not used here but it's the big difference is that this one is using plain markdown if you know markdown you don't need to learn Sphinx but the disadvantage yet is that you don't so easily integrate with a distinct code base but writing documentation or starting writing documentation zero barrier for starting so Sphinx barrier is you need to learn structured text yes but this is a very very easy way to start writing documentation it's incredibly simple so there are many options available so you have to choose which one works best for you we're not going to tell you that thing but like please use these things and write to documentation for whatever project whatever things you are working on it really helps people so many times I know like and all of you get frustrated over the developer whose module you may want to write but you can't find a single example working example which would work correct or even about how to get that source code properly so please work on those things like if you have any problem there are so many like if you go to the IRC channels like you can even ask on hash python there will be enough people who can actually point you out how to solve your issues like any students anyone no okay one two okay nice so just as a separate note the GSOC is like Google Samarov code is there and the PSF is also taking part doing a participation with all so many sub projects so if you want to apply any of the projects this might be a good time to open the proposal opens up tomorrow student proposals so thank you for coming down and my website is kushaldash.in I think and my Twitter handle is adred kushaldash so feel free to tweet to me or you'll find my email id kushaldash.jiva.com ask me anything if you have any problem I work so