All right, everybody, we're going to continue in the program, and we're going to talk
about a topic that's important in general, right, documentation, so, and I think it's also
really a pressing issue in the next community where we're trying various ways of addressing
this.
And now, they me, also known as Mini Jackson, is going to talk about this, in his talk
about, talk, or document your next code with Spinks, and a round of applause, please, for
they me, and have fun, enjoy the talk.
Thank you.
We'd have to know everyone, my name is Remy, and I'm here to propose you a way of
documenting your next project using Spinks.
So, at work, I have a very big next project, and maybe, like some of you, you have
a next project, and I'm pretty proud of my next project in the way that I show that
off is that I want people to use it, and so I have to do good documentation.
And in my documentation, I had, you know, user guys tutorials, and what not, and I came up on
a problem pretty quickly, is that I want to have a complete list of next-to-ass options,
packages, and functions that my project provides, and there isn't an easy way to do this
at least at the time that I search for it.
And so, if you want to have these resources on your documentation, you have basically
three solution.
The first one is to just give up, as I call it, just read the source code, and the
option to is kind of do it yourself, maybe you find the function that converts NixOS
options to mark down, maybe you find the Nix.project, I didn't add the time, but there is,
it's a bit involved to, to set up those, those projects for your documentation.
And option three is what I'm presenting here.
So, introducing Spinks.com, makes domain, the best name project in the planet, and it's
about documenting NixOS options, Nix packages, Nix libraries, using the Sphinx documentation
ecosystem.
It's the documentation is here, it's open source, and the European public license, thank
you for, thank you to my employer, the CEA, that allowed me to publish this.
So Sphinx, what is Sphinx is the most used documentation generator in the Python world,
but it's not limited to Python.
One aspect of Sphinx is that you have directives and walls, which are a fancy name of
that there are functions that you can call from Markdown, and using those functions, that
makes Sphinx a really good at generating reference API and cross-referencing to it.
It's made to be extensible, this is what my project is, it's an extension, and it supports
languages rather than Python, obviously.
And so, how do you set up this plugin?
So first, you have to have a Sphinx documentation project, you import the Sphinx-Contrib Nix
domain Nix repo using Flakes on Out, and then you set up the Sphinx extension in your
project's documentation, and then you pass all your Nix objects through an environment
viable in your documentation package, and then you use your direct new directives and
walls that this plugin provides in your documentation.
And in this presentation, I'm going to show exactly step three and four, and the rest
is left as an exercise to you.
So in your documentation package, you set up the Nix domain objects environment viable,
you call this big function called Documents Objects, you pass in the sources that you use.
So here, self is your project, you can set up all the sources like Nix packages.
You pass in the options that you want to document, you pass in the packages that you want
to document, so you can do this like this if you use Flakes, and you pass in the functions
that you want to document, and give it a name, because everyone calling their libraries
lab is confusing, and then that's it.
So in practice in your lockdown documentation, if you put this kind of text, this is calling
the Nix Potomotual Directives, so Directives is like a block level function for Macdown,
and as argument, I'm passing here the services that Autobar meaning that I want to document
every option that are under this prefix, and it will show you in the Render HTML, the options,
the type, a link to the source code, the default value, and all you want, basic to the same
for packages, if you don't pass any argument, it's going to document every package that you
specify in the environment viable, and you can see the description, sometimes the name version,
maintainers, and licenses, and for the functions, basically the same, and if you document your
functions, it's kind of like you document your Python functions, then you can have this really nice
rendering for specifying that the type of function, the parameters, return type, and whatnot.
So maybe you're going to say that's all really, but you've just even did invent today,
and overly complicated way of transforming Nix to Macdown, and that's kind of true, but the fun part
is that this things documentation project really understand that what you have generated are objects
from the Nix language, and you can do fun stuff with that. For example, you can do cross-ferencing,
so if you say see the Nix option, something something, and which is the package hello by default,
it will generate two links, which are going to be links to with the exact definition of this
function, no matter where they are in your documentation. So if you if you change your documentation
and move things around, those links are always going to be correct, and if, for example,
this option doesn't exist, the documentation system will warn you that you have a dangling reference.
You can also do external cross-ferencing, so if there is multiple project using things
and this plugin, you can say here is where these things project, and if in your documentation,
you reference an object that is in other documentation that you specified in this configuration,
it will actually download the inventory of objects in the external documentation and resolve
the links, so you can reference the resources in external projects. You do have to download
an inventory, so you have to build a new documentation without the Nix sandbox, but I think it's
useful in our future to develop the sandbox. Am I plug-in also generates some indices?
For example, you have the Nix option index, which is a full index of all the options that you
have in your documentation, and same for library, you also have a general index, and in here you
can see, for example, the Nix function functions that are in my plugin, but also the
documentation for the environment viable, the configuration value and directives and holds that my
plugin provides, so it's a neat feature. Sphinx can also generate other formats than the
HTML, you can generate PDFs, maybe you like PDFs, or maybe you have to use them, like I do in my
work. You can also generate man pages, so if you want a quick way of generating a man page with
all your options or your functions, then you can just point things to a document tree in your
documentation, and you can just generate them. I want to talk a bit about with the docs, which is
a platform where you can host your Sphinx documentation, you don't have to use it, but they
provide some nice features, like for example, link previews, so if you hover over a link,
it will show you a preview of the page. This sounds like a bit of a gimmick, but with this plugin,
if you hover over a, for example, an expansion here, it will actually show the function exactly
how it is, and I think it's pretty neat and pretty useful in this instance.
It also has a multi-version support, which is kind of a pain to do manually, so it can build your
documentation in several versions. For example, here you have latest, which is the main branch,
stable, which is an alias for the latest version, and versions can be either branches or or
types, and I have the wrong spinshot here, but it can also host PDF and IPA versions of your documentation,
and this is what RedDogs call the flyouts menu. It can also build your PRs if you want
GitHub or GitHub, so if someone opens a PR, the RedDogs is going to build the PR and show a preview
of the documentation for that PR, and with the warning that this is not an official
documentation instance, and you can also see here this really small button like here that says
show div, and it can actually show the differences between the main branch and the PR builds,
and here I've changed in the source codes of the next function, the description, and it
shows the div just fine. Some future work that I would like to do with this project is
obviously upstreaming it into next packages, so you don't have to import any repository.
I would like to have a way of cross-referencing options and packages and functions, which are
defined in next packages, which doesn't use this things ecosystem.
Support the Metadogs next-west option, I don't know if you know, but you can specify documentation
directly in your next-west modules, and I would like to support that, and with this create pages
automatically in your documentation, and I would like to sort you to warn if some of the
links objects are in preference in your documentation, and there's also a weird things
but we're using headers in object documentation, I would like to fix and I should
and love some time. So these are the useful links, so you have the documentation of the plugin
itself and the source code, and here you have my work project, if you want to see an instance,
a real instance of a big documentation that you can look at that, chances are you're not going
to want to use it unless you control industrial systems, but maybe you want to see an example.
And here are two resources that I find very useful for architecturing your documentation in a
more general manner, which I encourage you to read. And that's it.