Application With Internal Packages

00:00 I started with a single-file application. In the previous lesson, I advanced that to multiple files in a module. In this lesson, I’ll show you what changes when you start adding multiple modules, and I’ll give you a tour of one tool that you can use to help you with your documentation. In a larger application, you’re probably going to use multiple modules.

00:18 This becomes particularly important if you’re doing a GUI. Oftentimes when you structure a desktop GUI application, you’ll have modules for the UI and separate modules for the business logic, so this kind of multiple-modules setup becomes more important with that kind of application. So, some things that might change: You may add a bin/ directory.

00:35 The bin/ directory is where your executables for the user actually run. These are usually just thin wrappers to the entry points inside of your modules.

00:44 data/ directories: if you have data for your tests or data for your application, you want that separate from your actual code.

00:51 And of course, the bigger your application gets, the more likely you’re going to need documentation. Your users will appreciate it. The changes here aren’t really drastic; there’s just more nesting.

01:00 helloworld/ becomes a root place with multiple modules: a hello/ and a world/ inside of it. hello/ and world/ have a similar structure to the helloworld/ in the previous lesson. You’ve got your __init__, you’ve got some files—these are our modules. Of course, the same kinds of structure happens inside of tests/.

01:18 You want your test structure to more or less map to the module structure for the tests going with it. On the right-hand side, as I mentioned before, a bin/ directory is a good place for your entry point, so now I’ve got a program that is actually called helloworld, which would be what the user actually runs. A data/ directory, and then somewhere to put the docs, and the grayed-out stuff I discussed in the previous lesson. The bin/ directory: this holds the programs the user will execute. Typically, you drop the .py ending here because if you’re building a larger application, you’re probably focusing it on someone who isn’t actually a Python programmer and isn’t thinking about .py. They just want to run a program, so you name it the way you would name a program on your operating system.

02:00 There should be very little code logic inside of these. Typically, they’re just wrappers for your main modules’ entry points. This keeps them nice and clean. Finally, you can configure setup.py to actually point to this script so that when your module or wheel gets installed, the scripts in the bin/ directory can be put on the user’s path, making it easier for them to execute. data/ directories are for data; if your program’s got files that it needs to load to get things done—either for testing or for the program itself—it goes here.

02:28 This is really just a way of trying to keep things clean and keeping your data separate from your application. You can also put sub-directories inside of this folder if you want to separate production test data or any other sort of organizational hierarchy that makes sense for your application. As your application grows, the more important documentation becomes.

02:47 This is an often overlooked part of your package, but for it to be useful to users, they need to be able to know how to use it.

02:54 I typically use Sphinx to do my documentation. It’s based on the RST format, and it interacts with your pydoc comments so you can pull documentation out of your actual code.

03:04 Sphinx is available as a pip module, so you do your typical pip install. If you’re using Read the Docs to host your documentation, you can also install the Sphinx Read the Docs theme so everything looks like Read the Docs.

03:17 There’s a quickstart script that comes with Sphinx that helps you set up your configuration, and then once you’ve got everything going, make html is how you actually build your documentation. This is an example of the Read the Docs theme for the Hello World application that I’ve been showing you.

03:32 As you can see, nice and clean, a built-in search mechanism, links to the different modules. Simple, easy to use, easy to understand. Okay, so this is me inside of my docs/ folder.

03:46 You’ll notice Makefile, conf, hello, index, make, and world. The sphinx-quickstart script creates the Makefile, the conf, and the make.bat file for you, as well as a basic index.rst.

04:00 hello.rst and world.rst I’ve added with some information for the application. Up until now, I’ve been using Markdown for the README file. Because I’m using Sphinx here and Sphinx uses RST, I’ve actually changed the README file in the directory above to be an RST file.

04:16 They’re similar formats—it’s not a big difference.

04:20 The index.rst file is the landing page. I’ve included the README.rst up top. This allows me to use the README file twice—it needs to be in the root directory for GitHub to see it for the GitHub homepage, and I can include it here so that I don’t have to rewrite the main description for the project. The pipe here says to include the version number, which is inside of conf.py.

04:42 This is then a table of contents and it is importing hello.rst and world.rst, which I’ll show you in a second. Finally, it generates indexes and allows you to plug in search.

04:54 Most of this file is created for you by the quickstart, so you just need to add a tiny bit.

05:01 Now, I’ll show you hello.rst.

05:04 You can write whatever makes sense to describe this module for you. You can also take advantage of the automodule mechanism. This reads the docstrings out of helloworld.hello.hello and includes that information inside of the result.

05:19 I then do the same for the utils file. world.rst is similar to this file. By structuring it this way I can build out documentation for each one of my modules and then have it all tied together as part of index.rst.

05:35 Now I run make,

05:37 and Sphinx generates all of the documentation. At the bottom here, you’ll see the results are in _build/html. Sphinx allows you to also output to things like LaTeX and other formats, so if you want to do more than HTML, you can do that as well. So once again, here’s the result. This is the page produced by index.rst.

05:56 If you click on the link to the hello module you get hello.rst. This is the text from hello.rst, and these are the automodule statements pulled out of the code itself. Using the automodule and pydoc means you can keep your documentation with your code, which improves the likelihood that it’ll get adjusted when your code changes.

06:14 So, that was a multi-module application and the documentation to go with it. Next up, I’ll show you what a Django web application looks like.