Archive for the ‘Thoughts’ Category

Integrated subproject sites on readthedocs.org

Saturday, January 14th, 2017

This has been bothering me for a few years now, but in the FAQ for readthedocs it calls out the celery/kombu projects as an example of subprojects on RTD. And.. ok, I suppose it’s technically true, they are related projects, and they do use the subprojects. But if you didn’t know that kombu existed, you’d never be able to find it from the celery project. But they aren’t good examples, and as far as I can tell, no large project uses subprojects in an integrated/useful/obvious way.

Until I did it in December, anyways.

Now, one problem RobotPy has had is that we have a lot of subprojects. There’s robotpy-wpilib, pynetworktables, the utilities library, pyfrc… and until recently each one had it’s own unique documentation site, and there was some duplication of information between site. But it’s annoying, because you have to search all of these projects to find what you want, and it was difficult to discover new related content across projects.

However, I’m using subprojects on RTD now, and all of the subproject sites now share a unified sidebar that make them seem to be one giant project. There are a few things that make this work:

  • I automatically generate the sidebar, which means the toctree in all of the documentation subproject sites are the same.
  • They use intersphinx to link between the sites
  • But more importantly, the intersphinx links and the sidebar links are all generated based on whether not the project is ‘stable’ or ‘latest’.

The last point is really the most important part and requires you to be a bit disciplined. You don’t want your ‘latest’ documentation subproject pointing to the ‘stable’ subproject, or vice versa — chances are if the user selected one or the other, they want to stay on that through all of your sites. Thankfully, detecting the version of the site is pretty easy:

# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

# This is used for linking and such so we link to the thing we're building
rtd_version = os.environ.get('READTHEDOCS_VERSION', 'latest')
if rtd_version not in ['stable', 'latest']:
    rtd_version = 'stable'

Then the intersphinx links are generated:

intersphinx_mapping = {
  'robotpy': ('http://robotpy.readthedocs.io/en/%s/' % rtd_version, None),
  'wpilib': ('http://robotpy-wpilib.readthedocs.io/en/%s/' % rtd_version, None),
}

And  as a result, they point to the correct version of the remote sites, as do the sidebar links.

While this approach may not work well for everyone, it has worked really well for the RobotPy project. Feel free to use this technique on your sites, and check out the RobotPy documentation site at robotpy.readthedocs.io!

A partition recovery story

Sunday, May 23rd, 2010

So my dad tends to have a lot of really dumb computer problems that are either caused by him or some random virus/malware that he somehow manages to get on his system. And of course, I get to be ‘Mr. Helpdesk’ and help him fix them (sometimes), even though I’m 900 miles always from him.

His latest dumb computer trick involved some weird bug where he created a partition while Windows was running, formatted it, *moved* (not copied, but *moved*) a bunch of data to it, and then managed to get a blue screen without rebooting the system. For whatever reason, Windows decided that it didn’t want to write the partition or boot sectors for the hard drive correctly, and so he temporarily lost his data. In the past when I’ve had these kinds of problems with partition layouts, I’ve done things like manually recreating the MBR (a very long time ago) or using something like linux’s fdisk to set the parameters manually. However, the ‘easy’ tricks didn’t work for his problem this time, but I found this marvelous software that seems to do the trick:

http://www.cgsecurity.org/wiki/TestDisk

So hopefully it’s useful for you too!

Screw cygwin, I’m using GNUWin32

Wednesday, April 15th, 2009

For years I’ve hated cygwin (not for any particular reason, I just don’t like it) and have generally avoided using it because of that — but I’ve finally found a good alternative if you want useful *nix tools on Windows. Its called GNUWin32 and its a bunch of GNU utilities that have been ported to windows, and they’re quite lightweight also.

Its pretty sweet, I’ve actually had grep installed on my computer for quite awhile now, and just recently started installing more of these packages as my needs have evolved. I’d highly recommend it. The key thing to do is to add the bin directory to your path, so that way its accessible from cmd by default without having to screw around with typing out the full path name or anything.

The Cathedral and the Bazaar

Thursday, July 31st, 2008

So my work has a pretty decent library, and I was browsing through it and found The Cathedral and the Bazaar, by Eric S. Raymond. I had heard of it before, but had never gotten around to actually reading it. Seriously, its a wonderful book, and I recommend anyone involved (or thinking of being involved) in open source projects should read it. Definitely wish I had read it a few years ago… has a lot of good insight.