hpr-knowledge-base/hpr_transcripts/hpr0802.txt

Episode: 802
Title: HPR0802: Ana Nelson on Dexy software documentation
Source: https://hub.hackerpublicradio.org/ccdn.php?filename=/eps/hpr0802/hpr0802.mp3
Transcribed: 2025-10-08 02:42:55

---

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
It's more like a tool to help you construct your documentation, but then it gives you
a lot of standard patterns to follow to do that.
So what you can do is you can bring source code into say a latex document or an HTML document.
And then you can also show the output of running that source code or even get graphs or other
artifacts generated by the source code and pull those into your document.
And then at any point in time, if your source code changes, you can simply update the document
and those changes are reflected straight away.
Do you need to manually update the document or is that an automation process?
You need to manually update it, but it would be very straightforward.
There is a server version where you can refresh the page.
It'll check for updates and update it for you.
Saying that it's manually updated, it's actually a very straightforward process.
You literally type the command.
It figures out what files have changed.
And based on that, it'll update whatever has to be updated.
Okay, so it's not like you're going in an edge?
Not at all, not at all.
No, it's you simply type the command when you're ready to reflect the changes that have been
made.
And it'll very cleverly pick out what has been changed.
And then anything that depends on that will be re-run and anything that doesn't depend
on that won't be.
So if you have a huge project and you've just changed one little thing that nothing
else depends on, that's all that gets updated.
You don't have to re-run everything.
But if you've changed something that feeds through to everything else, it'll make sure
to update everything.
Okay, does it prompt you then for more information on that particular section?
No, it wouldn't, but it would just recognize that that section is what it relates to.
So the way you use it is you're going to actually start constructing a document.
And then at any point that you need to reference an element of code, you'll put in a reference
to that.
So you actually write your final document.
It's completely freeform.
It doesn't impose any structure on you like maybe spinks or some other tools would sort
of impose a structure.
This doesn't do that.
It really gives you the freedom to author whatever types of documents you want.
And then because of the way it's constructed, you can work this with any programming language
at all.
You can even use multiple languages in a single document.
So if you have some bash scripts along with a web application, you can document the
bash.
You can document your JavaScript and then you can document your PHP or your Ruby or
your Python or whatever your web app is written in as well, all of the same system.
And is it released on an open source license?
It is.
It's MIT licensed yet.
Okay.
And where can I get that?
You can get it at dexie.it or you can follow us dexyit on Twitter, dexie it on Twitter.
Okay.
So I do some Brawl code and some bash scripting and work.
How would it go about starting to document that?
I mean, the easiest thing you can do is you can start pulling out little extracts of
your code that you'd like to explain what they do to somebody.
You don't even have to actually execute the code.
You can just pull that extract.
So that part of it worked with absolutely any system.
And then if you also wanted to do some demonstrations of some code in practice, you could write
some standalone scripts that actually demonstrated features of your system.
And you could write a document where those sections were actually executed by the Perlin
interpreter and then you could show the output you could show how that was going to look
in practice.
Okay.
Fantastic.
So many people are involved in the project.
At the moment, it's just me.
I'm going to start expanding that out to look for new contributors very soon.
At the moment, it's a small project, but it is my full-time job to work on it, so it
does get a lot of love and attention.
So who pays you to work on that?
I'm working with a wonderful company called OpenGamma, who are based in London.
And I do their documentation for them.
And they're an open source company.
They understand how open source works and they're very, very supportive of dexie because
they recognize that it's valuable to them and it's also valuable to the community in
general.
So how can people contribute your help?
One thing people could do, certainly, even just using dexie and giving me feedback and
making feature requests is probably the best way to help at this point because I use dexie
in the way that I work, but obviously I'm not going to come up with every example.
So there are a lot of people now using it, which is great, and they're giving me wonderful
feedback and feature requests and bug reports.
And that's the most useful.
The only thing is to start developing custom filters with dexie.
So to start building up that ecosystem, and I probably won't get around to supporting
every single language myself, but it's very, very easy to write new filters for dexie.
So if you're using an obscure programming language that I haven't implemented support
for yet, you might want to create a filter for that.
Or if you just would like to maybe use dexie in a slightly different way than I may
have anticipated, you could take one of the existing filters and modify that.
That's a really easy way to get involved right now.
And that's a great way of giving me feedback on how you want to use it and how you do
your documentation.
Do you have a package for any of the distros, or sorry, one operation system doesn't
run on it.
It's pure Python.
It runs on pretty much anything.
I've done my best to have support for Windows as well.
That's not always the most up-to-date, but going forward, there certainly should be support
for every operating system.
And right now, it works straight away on Linux and Mac OS, and hopefully Windows usually.
OK, you heard it here, folks.
Documentation doesn't need to be painful.
Nerdos recording a podcast, as can be seen from this.
So thank you very much for coming on Hacker Public Radio.
And we look forward to more contributions coming to our community, hopefully.
OK, talk to you later, bye.
You have been listening to Hacker Public Radio, where Hacker Public Radio does our.
We are a community podcast network that releases shows every weekday on their free Friday.
Today's show, like all our shows, was contributed by a HBR listener by yourself.
If you ever consider recording a podcast, then visit our website to find out how easy
it really is.
Hacker Public Radio was founded by the Digital Dog Pound and the Infonomicom Computer
Club.
HBR is funded by the binary revolution at binref.com.
All binref projects are crowd-responsive by linear pages.
From shared hosting to custom private clouds, go to lunarpages.com for all your hosting needs.
Unless otherwise stasis, today's show is released under a creative comments, attribution,
share a line, read those own license.