Now, I don't know about you, but I don't really want to include the output HTML, images, CSS, JS, or anything in my documentation repository. toctree::, let's tell Sphinx to include everything we ReST-ify: Let's do that now.Įdit the mydox/source/index.rst file that was created during Sphinx configuration. Not very exciting, is it? Notice how your first_doc.rst doesn't appear anywhere on that page? That's because we didn't tell Sphinx to put it there. Go ahead and take a look at your new mydox/docs/index.html file in the Web browser of your choosing. If you see something like that, you're in good shape. home/jvanderlinden/mydox/source/first_doc.rst:: WARNING: document isn't included in any toctree Updating environment: 2 added, 0 changed, 0 removed If your setup is anything like mine, you should see some output similar to this:īuilding : targets for 2 source files that are out of date Execute the following command somewhere under your mydox repository: You should now be at a stage where you can safely commit changes to your repository and have Sphinx build your HTML documentation. We'll do our work in the source directory. If you followed the same steps I did (I separated the source and build directories), you should see three new files in your mydox repository: Where "builder" is one of the supported builders, e.g. Use the Makefile to build the docs, like so: source/index.rst and create other documentation You should now populate your master file. > Create Windows command file? (Y/n) : nįinished: An initial directory structure has been created. `make html' instead of invoking sphinx-build > ifconfig: conditional inclusion of content based on config values (y/N) :Ī Makefile and a Windows command file can be generated for you so that you > jsmath: include math, rendered in the browser by JSMath (y/N) : > pngmath: include math, rendered as PNG images (y/N) : > coverage: checks for documentation coverage (y/N) : > todo: write "todo" entries that can be shown or hidden on build (y/N) : > intersphinx: link between Sphinx documentation of different projects (y/N) :
#Mercurial windows hook on commit add comment code#
> doctest: automatically test code snippets in doctest blocks (y/N) : > autodoc: automatically insert docstrings from modules (y/N) : Please indicate if you want to use one of the following Sphinx extensions: > Name of your master document (without suffix) : Normally, this is "index", but if your "index"ĭocument is a custom template, you can also set this to another filename. "contents tree", that is, it is the root of the hierarchical structure One document is special in that it is considered the top node of the Only files with this suffix are considered documents. Python the version is something like 2.5 or 3.0, while the release is Sphinx has the notion of a "version" and a "release" for the The project name will occur in several places in the built documentation. > Name prefix for templates and static dir : You can enter another prefix (such as ".") to replace the underscore. Inside the root directory, two more directories will be created "_templates"įor custom HTML templates and "_static" for custom stylesheets and other staticįiles. > Separate source and build directories (y/N) : y "source" and "build" directories within the root path. You have two options for placing the build directory for Sphinx output.Įither, you use a directory "_build" within the root path, or you separate Please enter values for the following settings (just press Enter toĪccept a default value, if one is given in brackets).
Welcome to the Sphinx quickstart utility. It's pretty safe to accept the defaults, in my opinion. This is a wizard that will walk you through the configuration process for your project. The next step is to configure Sphinx for our project. Just like I take notes to remind myself of stuff at work, I want to do that again for this automated ReST->HTML magic-I want to be able to do this in the future! I figured I would make my notes even more public this time, so you all can enjoy similar bliss. I then wrote a small Web server using Python, so people within the company network could access the latest version of my notes without much hassle. I setup Sphinx to prettify my documentation. However, these individuals probably wouldn't appreciate reading ReST markup as much as I do, so I decided to do something nice for them.
Lucky for me, I had taken some nice notes! On several occasions, I had some of the other guys in the company ask me for some clarification on some things I had taken notes on. I've gotten into the habit of taking my notes using reStructured Text, which shouldn't come as any surprise to any of my regular visitors. I often find myself taking notes about various aspects of my job that I feel I would forget as soon as I moved onto another project.
0 kommentar(er)
