7c8efd2228
- MCP server with stdio transport for local use - Search episodes, transcripts, hosts, and series - 4,511 episodes with metadata and transcripts - Data loader with in-memory JSON storage 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
154 lines
7.0 KiB
Plaintext
154 lines
7.0 KiB
Plaintext
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.
|