Set up MkDocs and Snipe-IT

[MatthewCroughan]

We need

• Inventory Management
• Documentation
• Network Documentation

I've read a lot lately, and I've come to the conclusion that there are three tools that will wholly implement those three requirements. All three solutions are completely open source and can be self-hosted on a VPS or through Github/Gitlab pages.

Snipe-IT (Inventory Management)

These images speak for themselves. Imagine instead of hardware such as MacBooks and iPads, we tracked consumables such as filament, wood and anything from the IoT Lending library that we have not yet implemented successfully. https://github.com/DoESLiverpool/wiki I am sure we will find more uses for this.

MkDocs (Documentation)

MkDocs is an alternative to using Sphinx and RST files to make fantastic documentation. It uses standard markdown. Here's some example documentation that I would love to aspire to:

https://docs.micropython.org/en/latest/esp32/quickref.html https://docs.traefik.io/getting-started/quick-start/

Imagine instead of the former esp32 doc, we have documented one of our machines or devices on the network. The current wiki does not allow for proper layouts and we are limited by what Github allows ( No animated pngs, video embeds, etc. ). MkDocs allows for richer docs in the same markdown format. We can place this on docs.doesliverpool.com and it can be hosted by Github pages, just as we currently do with our Github integrated wiki. There will be no real difference between the two, just that one offers a lot more expression.

Netbox (Network Documentation)

The network and the devices on it are not documented, and documenting them statically in text is not good enough, since these things are highly variable and subject to change. The netbox interface was initially conceived of by the engineers at DigitalOcean. We can interlink the MkDocs for each machine into this network view in a custom field and say "Docs for this machine", providing a manual for each device.

[MatthewCroughan]

360 is a prerequisite to completion of this issue.

[MatthewCroughan]

I've set up Snipe-IT on a VPS and have asked @RussCoty to help me attempt to inventory parts of the CNC Room as a demonstration sometime next week. We will also be generally improving the CNC room as outlined in #1492

[amcewen]

Why do we need all those things?

Retraining the community onto a different documentation tool just to get video and a specific type of animated image (presumably these are all animated GIFs?) seems quite a high cost.

The IoT lending library had an extremely fancy QR code inventory system. Presumably that wasn't used much?

We've survived for nearly nine years with the laser stock control system we have at present, so what's the need for a replacement?

Given that you failed to follow a using-small-tools system that was as simple as "make sure you return the forceps to my desk when you're finished with them", what makes you think that a more complicated system will work better?

[MatthewCroughan]

Allow me to demo it and make your conclusions once I have something to demonstrate instead of pre-emptively shutting me down. Thank you. @amcewen

[MatthewCroughan]

Additionally, I know that it's true that I have made X amount of issues and left them unresolved for X amount of time. But no harm can come from adding more and failing more, since I may succeed this time. We won't know until I can demo it.

Why do we need all those things?

Maybe we don't. Let's find out.

The IoT lending library had an extremely fancy QR code inventory system. Presumably that wasn't used much?

I do not know much about this, I just know that it didn't work so I'm trying something different.

Retraining the community onto a different documentation tool just to get video and a specific type of animated image (presumably these are all animated GIFs?) seems quite a high cost.

Automation. Nothing the community does needs to be changed, it's possible and simple to take existing wiki stuff and port it to this automatically as mentioned. Additionally, it's still MD and can be previewed in the Github editor all the same. This will require demonstration for you to believe, which I will provide in due time. ( I know I can be incorrect here, so reserve your judgement )

Given that you failed to follow a using-small-tools system that was as simple as "make sure you return the forceps to my desk when you're finished with them", what makes you think that a more complicated system will work better?

Other people's personal tools and general laziness (that I do admit to) is out of scope for what will be managed by Snipe-IT. It will allow anybody to mark tools as missing, checked out, etc. It will provide a method of keeping track that is better than what we currently have. There are github issues here for "Out of stock", but none for "Tools missing" or "Checked out". Not that we couldn't do this with GH Issues, I just want to explore this as an alternative, so again let me demonstrate this first. I cannot complete this in a matter of weeks, this will be a matter of months.

[MatthewCroughan]

One last thing. Everything done here will contribute to the Inventory effort. Obviously everything will be exportable in CSV and manipulable into whatever format you can dream of. It's not as if the effort to inventory things is going to be wasted.

[MatthewCroughan]

I have evaluated Netbox. I think it's potentially incredibly useful for administrators of the network, however the network is not complex enough to warrant using it at this time. I thought it would be useful to use as a frontend to demonstrate the services that we provide at DoES and whether they are online, or offline for example. But it is not. The reason it is not useful as a user facing frontend is because it requires user auth, permissions, a database AND it has security vulnerabilities. This is designed for administrators on a LAN, it has a great API for hooking into possible events that could occur on the network, such as when services are down, etc. However, in conclusion, it is not what I initially thought it was.