About the Author:

Spotlight on Sphinx: Python Docs For Everyone

October 13th, 2017

If you’ve ever looked at the Python documentation, you’ve seen Sphinx in action.

Sphinx is an open-source project that allows people to automatically generate static websites for Python documentation. Besides code-heavy documentation, it can also be used as a static site generator.

What is Sphinx?

Sphinx is a Python project that takes in reStructuredText and outputs static web pages. It is most commonly used to host documentation. With Sphinx installed, you can write comments in your code similar to how you would with JavaDoc, and it will pull in all those comments to provide a big picture of your functions and classes. This can be extremely helpful as a programming reference, and since it pulls directly from the code, you don’t have to worry about it getting out of sync.

Who’s using it?

Sphinx was originally created to host the official Python documentation, but it’s only grown from there. Many popular libraries use Sphinx to host their documentation, and it’s become something of an industry standard among Python developers.

In addition, the popular documentation site Read The Docs makes this process even easier by allowing developers to host and update their Sphinx docs by connecting the repository and building the docs just like you would code. This “docs-as-code” approach helps ensure maximum compatibility between the code and the documentation, and helps mitigate documentation debt.

Here are some notable companies or libraries using Sphinx to host their websites or documentation:

It doesn’t stop at just documentation. Some people have written their personal sites, courses, or even whole books using Sphinx:

How can Sphinx help me?

Now that you know about all the great things Sphinx can do, I bet you’re wondering how you can use it in your work. Sphinx is adaptable enough to work for many use cases, but it really shines at documenting code, Python code in particular.

If you’re writing Python software as part of your job and having trouble maintaining the docs (or God forbid, you don’t have any docs!), Sphinx is definitely worth a try. It’s free, open source, and there are a variety of resources and tutorials out there to help you customize it to your needs.

Sphinx is great when you have structured information. In this way, Sphinx might not be such a great choice if you’re trying to host your latest novel, but it is a good idea for technical manuals with a complex table of contents that people will need to navigate. Another great feature of Sphinx is that it comes with search built-in, so you don’t have to worry about pulling in another package to do the heavy lifting for you.

Set up your first Sphinx site

Ready to get started? Let’s go through the basics of installing and setting up your first Sphinx site.

You can install Sphinx from PyPI (Python Package Index) by running this command:

$ pip install Sphinx

Once Sphinx is installed, run sphinx-quickstart from your project folder to initialize a project there:

$ sphinx-quickstart
    1. Sphinx-quickstart will go through and ask you a bunch of questions. This sets up some initial configuration values, but you can always go back and change them later. For most projects the defaults will suffice. Be sure to enter your project’s name and the project author when prompted.
    2. If you’re wanting to generate docs from your Python code, be sure to enable the autodoc extension (disabled by default).
    3. When sphinx-quickstart is finished running, you should have several new files and folders used to configure and manage your site. If you need to change any of the configuration values in the future, you can do that in conf.py.
    4. The Makefile is what allows us to build the documentation and package it into HTML for the web. To build the example skeleton project, run:
$ make html

The output files should be in _build/html. Navigate there now:

$ cd _build/html

The home page for our site is index.html. Open that file in a web browser to see the example project:

$ open index.html

You should see the basic layout of your new Sphinx site.

sphinx site

Congratulations! You have Sphinx up and running.

For next steps on how to add posts and customize Sphinx, I recommend Brandon’s Sphinx Tutorial (PDF). It’s both informative and easy to follow.

Now that you know about Sphinx, go out there and Write The Docs!

About the Author:

Windows Store Applications with jQuery 2.0

March 29th, 2013

appendTo has been betting on jQuery and JavaScript from the beginning, believing Atwood’s Law that any application that can be written in JavaScript, will eventually be written in JavaScript. Naturally we were very excited when Microsoft announced that Windows Store applications on Windows 8 could be written in traditional web languages like HTML5, CSS3, and JavaScript.

On November 2, during the //Build/ 2012 conference, appendTo had the privilege of co-presenting jQuery for Windows Store applications to the web community. Efforts were then refocused to contributing necessary changes back into the jQuery project, and eliminating any chance of having to maintain a specialized version of jQuery for Windows Store applications.

In parallel to our efforts with jQuery and Windows Store applications, the jQuery team has also been actively developing the much-anticipated version 2.0 (you can currently test with the 2.x pre-release version) of their library. This version is noted for dropping much of the necessary baggage used to support over a decade of browsers. During this process, appendTo has been working to introduce changes back into jQuery core.

Windows Store Applications with jQuery 2.0

We’re excited to announce that our tests indicate that the soon to be released jQuery 2.0 will be right at home in your Windows Store applications. It is our position that while jQuery works well in Windows 8, some of our common conventions will need to be re-evaluated. appendTo addresses some of these in our Nettuts article Building Windows Store Applications with jQuery 2.0.

We are very grateful to the Microsoft Open Technology Group for the technical support they provided us while we were testing and researching how to update jQuery to work with Windows Store Applications. The Windows Developer Blog has a post up today detailing more about our work.

Moving forward, appendTo will continue listening to developer feedback from those actively using jQuery 2.0 in Windows Store applications. It is our goal to see jQuery thrive outside of the browser as successfully as it has inside the browser.

appendTo offers JavaScript Training Courses for Developer Teams.

About the Author:

VSDoc for jQuery Mobile In-Development

November 16th, 2010

While [jQuery Mobile](https://github.com/jquery/jquery-mobile) is still in early development, we’ve put together a simple VSDoc file containing the jQuery Mobile-specific methods which have been documented thus far. The jQuery Mobile VSDoc is available now for download on our [jQuery VSDoc Community](https://appendtonew.wpengine.com/community/vsdoc) page.Formal documentation for jQuery Mobile is still being assembled at the moment, so this VSDoc was put together by hand, unlike the VSDoc for jQuery proper which is automatically generated.

As always, please feel welcome to have a look at, or fork, the [Git Repository](https://github.com/appendto/jquery-vsdoc) where all of our VSDoc material lives.

About the Author:

VSDoc for jQuery 1.4.4, with early VSDoc Generator Released

November 15th, 2010

On the heels of the jQuery 1.4.4 release, we are pleased to announce the availability of the VSDoc for jQuery 1.4.4. It is available for download immediately on our jQuery VSDoc Community page.

Additionally, for this release, we’re also releasing an early version of our C# generator that we’re currently using to create the VSDoc files. The generator consumes the XML feed directly from the jQuery API site, ensuring that the VSDocs that are generated are providing the latest documentation. The generator is a part of the GitHub repository that’s hosting the completed VSDoc files.

About the Author:

Visual Studio 2010 vsdoc for jQuery 1.4.3 Now Available

November 10th, 2010

We’re excited to release the Visual Studio 2010 vsdoc file for jQuery 1.4.3. It is now available on our website, in our Community section on the jQuery VSDoc page.

We’re committed to supporting the Enterprise community, and will be maintaining the VSDoc file going forward for each new release of jQuery.

– The appendTo Team