WEBVTT 00:00.000 --> 00:13.280 All right, everybody, we're going to continue in the program, and we're going to talk 00:13.280 --> 00:20.240 about a topic that's important in general, right, documentation, so, and I think it's also 00:20.240 --> 00:24.240 really a pressing issue in the next community where we're trying various ways of addressing 00:24.240 --> 00:25.240 this. 00:25.240 --> 00:30.840 And now, they me, also known as Mini Jackson, is going to talk about this, in his talk 00:30.840 --> 00:37.040 about, talk, or document your next code with Spinks, and a round of applause, please, for 00:37.040 --> 00:41.240 they me, and have fun, enjoy the talk. 00:41.240 --> 00:42.240 Thank you. 00:42.240 --> 00:53.640 We'd have to know everyone, my name is Remy, and I'm here to propose you a way of 00:53.640 --> 00:57.800 documenting your next project using Spinks. 00:57.800 --> 01:03.960 So, at work, I have a very big next project, and maybe, like some of you, you have 01:03.960 --> 01:08.400 a next project, and I'm pretty proud of my next project in the way that I show that 01:08.400 --> 01:13.720 off is that I want people to use it, and so I have to do good documentation. 01:13.720 --> 01:20.600 And in my documentation, I had, you know, user guys tutorials, and what not, and I came up on 01:20.600 --> 01:28.600 a problem pretty quickly, is that I want to have a complete list of next-to-ass options, 01:28.600 --> 01:34.360 packages, and functions that my project provides, and there isn't an easy way to do this 01:34.360 --> 01:37.440 at least at the time that I search for it. 01:37.440 --> 01:42.240 And so, if you want to have these resources on your documentation, you have basically 01:42.240 --> 01:43.240 three solution. 01:43.240 --> 01:49.960 The first one is to just give up, as I call it, just read the source code, and the 01:49.960 --> 01:56.200 option to is kind of do it yourself, maybe you find the function that converts NixOS 01:56.200 --> 02:02.600 options to mark down, maybe you find the Nix.project, I didn't add the time, but there is, 02:02.600 --> 02:08.040 it's a bit involved to, to set up those, those projects for your documentation. 02:08.040 --> 02:11.040 And option three is what I'm presenting here. 02:11.040 --> 02:18.520 So, introducing Spinks.com, makes domain, the best name project in the planet, and it's 02:18.520 --> 02:24.320 about documenting NixOS options, Nix packages, Nix libraries, using the Sphinx documentation 02:24.320 --> 02:25.320 ecosystem. 02:25.320 --> 02:32.320 It's the documentation is here, it's open source, and the European public license, thank 02:32.320 --> 02:38.360 you for, thank you to my employer, the CEA, that allowed me to publish this. 02:38.360 --> 02:44.880 So Sphinx, what is Sphinx is the most used documentation generator in the Python world, 02:44.880 --> 02:49.680 but it's not limited to Python. 02:49.680 --> 02:56.240 One aspect of Sphinx is that you have directives and walls, which are a fancy name of 02:56.240 --> 03:02.280 that there are functions that you can call from Markdown, and using those functions, that 03:02.280 --> 03:08.960 makes Sphinx a really good at generating reference API and cross-referencing to it. 03:08.960 --> 03:14.600 It's made to be extensible, this is what my project is, it's an extension, and it supports 03:14.600 --> 03:18.200 languages rather than Python, obviously. 03:18.200 --> 03:21.880 And so, how do you set up this plugin? 03:21.880 --> 03:27.240 So first, you have to have a Sphinx documentation project, you import the Sphinx-Contrib Nix 03:27.240 --> 03:32.360 domain Nix repo using Flakes on Out, and then you set up the Sphinx extension in your 03:32.360 --> 03:38.320 project's documentation, and then you pass all your Nix objects through an environment 03:38.400 --> 03:45.360 viable in your documentation package, and then you use your direct new directives and 03:45.360 --> 03:47.920 walls that this plugin provides in your documentation. 03:47.920 --> 03:54.800 And in this presentation, I'm going to show exactly step three and four, and the rest 03:54.800 --> 03:58.400 is left as an exercise to you. 03:58.400 --> 04:04.520 So in your documentation package, you set up the Nix domain objects environment viable, 04:04.520 --> 04:11.760 you call this big function called Documents Objects, you pass in the sources that you use. 04:11.760 --> 04:17.880 So here, self is your project, you can set up all the sources like Nix packages. 04:17.880 --> 04:21.480 You pass in the options that you want to document, you pass in the packages that you want 04:21.480 --> 04:26.280 to document, so you can do this like this if you use Flakes, and you pass in the functions 04:26.280 --> 04:30.000 that you want to document, and give it a name, because everyone calling their libraries 04:30.080 --> 04:35.280 lab is confusing, and then that's it. 04:35.280 --> 04:43.760 So in practice in your lockdown documentation, if you put this kind of text, this is calling 04:43.760 --> 04:51.040 the Nix Potomotual Directives, so Directives is like a block level function for Macdown, 04:51.040 --> 04:57.280 and as argument, I'm passing here the services that Autobar meaning that I want to document 04:57.360 --> 05:05.840 every option that are under this prefix, and it will show you in the Render HTML, the options, 05:05.840 --> 05:13.200 the type, a link to the source code, the default value, and all you want, basic to the same 05:13.200 --> 05:20.080 for packages, if you don't pass any argument, it's going to document every package that you 05:20.080 --> 05:26.560 specify in the environment viable, and you can see the description, sometimes the name version, 05:26.560 --> 05:33.840 maintainers, and licenses, and for the functions, basically the same, and if you document your 05:33.840 --> 05:39.440 functions, it's kind of like you document your Python functions, then you can have this really nice 05:40.560 --> 05:47.040 rendering for specifying that the type of function, the parameters, return type, and whatnot. 05:48.800 --> 05:54.400 So maybe you're going to say that's all really, but you've just even did invent today, 05:54.400 --> 06:01.360 and overly complicated way of transforming Nix to Macdown, and that's kind of true, but the fun part 06:01.360 --> 06:08.880 is that this things documentation project really understand that what you have generated are objects 06:08.880 --> 06:14.800 from the Nix language, and you can do fun stuff with that. For example, you can do cross-ferencing, 06:14.800 --> 06:23.840 so if you say see the Nix option, something something, and which is the package hello by default, 06:23.920 --> 06:28.160 it will generate two links, which are going to be links to with the exact definition of this 06:28.160 --> 06:35.120 function, no matter where they are in your documentation. So if you if you change your documentation 06:35.120 --> 06:43.840 and move things around, those links are always going to be correct, and if, for example, 06:43.840 --> 06:49.520 this option doesn't exist, the documentation system will warn you that you have a dangling reference. 06:50.400 --> 06:55.840 You can also do external cross-ferencing, so if there is multiple project using things 06:55.840 --> 07:03.280 and this plugin, you can say here is where these things project, and if in your documentation, 07:03.280 --> 07:09.760 you reference an object that is in other documentation that you specified in this configuration, 07:09.760 --> 07:17.040 it will actually download the inventory of objects in the external documentation and resolve 07:17.200 --> 07:25.200 the links, so you can reference the resources in external projects. You do have to download 07:25.200 --> 07:30.080 an inventory, so you have to build a new documentation without the Nix sandbox, but I think it's 07:30.800 --> 07:37.840 useful in our future to develop the sandbox. Am I plug-in also generates some indices? 07:37.840 --> 07:42.800 For example, you have the Nix option index, which is a full index of all the options that you 07:42.880 --> 07:49.360 have in your documentation, and same for library, you also have a general index, and in here you 07:49.360 --> 07:55.760 can see, for example, the Nix function functions that are in my plugin, but also the 07:55.760 --> 08:03.200 documentation for the environment viable, the configuration value and directives and holds that my 08:03.200 --> 08:10.880 plugin provides, so it's a neat feature. Sphinx can also generate other formats than the 08:10.880 --> 08:17.040 HTML, you can generate PDFs, maybe you like PDFs, or maybe you have to use them, like I do in my 08:17.040 --> 08:23.840 work. You can also generate man pages, so if you want a quick way of generating a man page with 08:23.840 --> 08:31.040 all your options or your functions, then you can just point things to a document tree in your 08:31.040 --> 08:38.880 documentation, and you can just generate them. I want to talk a bit about with the docs, which is 08:38.960 --> 08:44.400 a platform where you can host your Sphinx documentation, you don't have to use it, but they 08:44.400 --> 08:51.520 provide some nice features, like for example, link previews, so if you hover over a link, 08:51.520 --> 09:01.200 it will show you a preview of the page. This sounds like a bit of a gimmick, but with this plugin, 09:01.280 --> 09:09.280 if you hover over a, for example, an expansion here, it will actually show the function exactly 09:10.480 --> 09:16.000 how it is, and I think it's pretty neat and pretty useful in this instance. 09:17.840 --> 09:26.160 It also has a multi-version support, which is kind of a pain to do manually, so it can build your 09:26.240 --> 09:33.360 documentation in several versions. For example, here you have latest, which is the main branch, 09:33.360 --> 09:39.200 stable, which is an alias for the latest version, and versions can be either branches or or 09:39.200 --> 09:48.480 types, and I have the wrong spinshot here, but it can also host PDF and IPA versions of your documentation, 09:49.120 --> 09:57.280 and this is what RedDogs call the flyouts menu. It can also build your PRs if you want 09:57.280 --> 10:04.880 GitHub or GitHub, so if someone opens a PR, the RedDogs is going to build the PR and show a preview 10:04.880 --> 10:12.080 of the documentation for that PR, and with the warning that this is not an official 10:12.080 --> 10:22.560 documentation instance, and you can also see here this really small button like here that says 10:22.560 --> 10:31.920 show div, and it can actually show the differences between the main branch and the PR builds, 10:31.920 --> 10:38.800 and here I've changed in the source codes of the next function, the description, and it 10:38.800 --> 10:46.800 shows the div just fine. Some future work that I would like to do with this project is 10:46.800 --> 10:52.800 obviously upstreaming it into next packages, so you don't have to import any repository. 10:54.240 --> 10:59.280 I would like to have a way of cross-referencing options and packages and functions, which are 10:59.280 --> 11:03.200 defined in next packages, which doesn't use this things ecosystem. 11:03.280 --> 11:10.960 Support the Metadogs next-west option, I don't know if you know, but you can specify documentation 11:10.960 --> 11:18.240 directly in your next-west modules, and I would like to support that, and with this create pages 11:18.240 --> 11:23.200 automatically in your documentation, and I would like to sort you to warn if some of the 11:23.200 --> 11:27.680 links objects are in preference in your documentation, and there's also a weird things 11:27.920 --> 11:32.720 but we're using headers in object documentation, I would like to fix and I should 11:32.720 --> 11:40.320 and love some time. So these are the useful links, so you have the documentation of the plugin 11:40.320 --> 11:46.000 itself and the source code, and here you have my work project, if you want to see an instance, 11:46.000 --> 11:53.440 a real instance of a big documentation that you can look at that, chances are you're not going 11:53.520 --> 11:59.600 to want to use it unless you control industrial systems, but maybe you want to see an example. 12:00.320 --> 12:05.840 And here are two resources that I find very useful for architecturing your documentation in a 12:05.840 --> 12:11.040 more general manner, which I encourage you to read. And that's it.