Hi! I’m learning code: I’ve been doing a bit of JavaScript, and now i’m switching to TypeScript before going through frameworks.
One thing i’m quite missing is the possibility to have a personal documentation environment: something that let me write documentation on what i’m learning WHILE writing code and following my courses, using something like typedoc or javadoc.
I have been using Obsidian, that is good for markdown content, and i can generate docs with typedoc-markdown-plugin that i can then open on obsidian. However i would like to have both my code and my docs all togheter, not for a single project but for all the courses and little projects i’m doing, having it all togheter stored in one place, and possibly being able to share it as a portfolio in the future.
I don’t specifically need to show the code in this environment, i just need the docs to be visible and to be pointing to the specific sections of the environment holding my code (wich can be github links like the ones that typedoc automatically add). I would like to have one directory for each project containing both my code and my docs.
Something like a programming digital garden! But integrated with tools that generate documentation from my code.
I’ve tried the typedoc-hugo-plugin to host a static docs website with Hugo, but it’s not quite mantained and came with a lot of bugs, like broken links.
I’m trying to use Docusaurus and docusaurus-plugin-typedoc; it looks quite good, however i understood it is designed more to hold documentation for a single big project than for a series of small (learning oriented) projects. You need to configure each extra (more than one) docs folder to get it work properly, which is something i would avoid, if possible.
I love all the TSdoc standard thing, but i don’t really know how to put everything togheter.
Hackmd.io is my go to.
Seems neat, thanks
I’ve looked at the webpage, a blog post “How I use HackMD in FOSS”, the intro to the documentation, the features page in the documentation, and I still can’t find out what this thing is supposed to be doing. Is it a wiki? Is it a tool to extract documentation from source code?
Just markdown docs really in a simple format to export for documentation.
There is a vim plugin called vimwiki which is pretty much what you’re looking for I think, but if you’re not using (neo)vim this won’t make much sense I guess. Other than that I’d probably just set up a GitHub gist or repo with your doc stuff
There is a learning curve, but emacs org-mode sounds exactly like what you want.
With org-mode you can have your docs and your code in the same place or use your docs to create and link to different files.
You can even run your code inside your docs and have it execute on a networked computer without ever leaving your doc.
https://www.youtube.com/watch?v=34zODp_lhqg
And with org-roam, you can keep the same functionality you are used to with obsidian.
Emacs is a bit of a rabbit hole however. So if you want to keep things simple you could just use git.
Git has its own learning curve but it’s pretty much a requirement everywhere code is developed and released professionally so it’s a good idea to have some experience with it.
I’d suggest having different repos for your different projects, and either one single readme.md file in each repo for all your docs or using the wiki feature that is built into most free git web UIs like GitHub and gitlab.
Once on git, it’s trivial to link to specific files or even individual lines in your repo.
My half-solution to this has always been to refer to where I’m working in my notes, like a file, method name, and maybe control structure if warranted. I’ve never needed to take that final step (hence half-solution), but this carries about enough information that someone could hack together a quick program to merge the notes and code in a reasonable way.
While (as I say) I’ve never specifically needed it, though, at work I’ve often wanted to do that and take the next step of sifting through version control, the ticketing system, and team chats to pull a complete view of what’s been happening around a particular chunk of code. I point that all out, because I think that you’re on the right track, however you ultimately solve that problem for yourself.
For python there’s jupityr. It’s mostly used as a lab notebook by data scientists and I’ve barely used it but I think it integrates notes and code. It looks like some people are trying to make it work for javascript.
You could also use fossil as SCM, it is small, a single executable and has a wiki (and bug tracker) in it, so you could keep your documentation and code close together
