movedo / movedo Goto Github PK

As of now, MoVeDo is quite invasive into a project since MoVeDo is essentially distributed by means of a submodule into a project. For my projects, I would prefer MoVeDo to be a standalone tool. I could see two different solutions where one is more different from the current setup than the other:

• clone MoVeDo in a directory outside the project and refer to it with an environment variable such as MOVEDO_DIR,
• create full blown releases of the tool.

The two options don't exclude each other by the way, where the former is for development purposes and the latter for more stable solutions.

CodiMD (and co.) support an [TOC] in-document command, to be placed where the table of contents shall be in the document when generating the (HTML) output.

GitLab supprts [[_TOC_]], which works in the same way.

Pandoc supports neither (in none of the Markdown flavors), so we need hackery for that!

Idea

Check if a document to be converted has either [TOC] or [[_TOC_]] present (e.g. using sed),
and if so, remove it, and use the --toc command line option to pandoc,
which generated a table of contents in the very beginning of the document.

e.g where the version is displayed, or as an extra "source" link below or in the title page.

have a command to create an index page, containing links to all the generated pages.

probably best to do it in Markdown, and also convert it just to markdown and HTML, but make it contain links to all the generated versions (MD, HTML and PDF) of the documents.

This script would then likely be called from a CI script, and its output be published on the projects "pages", together with the other generated output.

Probably projvar genrated vars can be useful for the content, and maybe a pdsite extension, or a pandoc filter can do the inserting.

this one would be handy to have a nice and clean PDF output that can be adapted easily

As of now, it does only insert the actual version in the generated PDFs, not the HTML output (or at least not all of it).

Probably, instead of inserting the version in PDF and HTML, we should already add it in the Markdown that ends up under build/gen_sources/, as it then works for all possible generated outputs, and also because that markdown might be considered an output by its self, and might be distributed as the documentation for a specific version by its self.

NOTE: use sed or awk` for adding/replacing the version in the markdown. IT is by far the easiest and probably the cleanest way to get there.

NOTE: I already started working on this locally (NOTE to self: in the local OSEG/ohs repo).

hello all of you!
I am working on something that is somehow related to this. though it is
more about hardware documentation, the question is a more general one,
about an architecture for .. tools/plugins/scripts that are useful in
OSH documentation repos.

Introduction through an example

So... let's imagine we are documenting a machine, that is made up of
some mechanical parts and some electronics. The mechanical parts are
designed in FreeCAD (FC), the electronic ones in KiCad (KC).
So our repo contains some Markdown files, some FC files and some KC
files. In our CI/CD (build-bot) job, we want to generate renders in SVG
and/or PNG for the FC and KC files, and STL files from the FC files, and
Gerbers from the KC files (that last one I am working on/have mostly
done now). Because FC uses a binary format, we also want to pre-process
these files with a git filter before storing them in the repo (for
example with ReZipDoc).

MoVeDo (pronunciation is like an Italian person would say it, btw.)
handles the Markdown part, ReZipDoc the FC storage issue, what I am
working on now the Gerbers for KC, and the rest is still to be done, and
we need more tools for FC and KC, but probably also for other formats
not present in this example (OpenSCAD would be a candidate).

The Question

How to best organize this all?

I imagine a kind of flexible system of small tools, that can also be
replaced one by one, if desired, and are easy to modify.

My personal wishes for the requirements would be:

• to prevent lock-ins - our whole system or parts of it should be replaceable with alternatives
• to make it modular
• to support a modular documentation style - hardware is usually made up of modules, which might be recombined into other hardware; the documentation should support this gracefully
• to keep common functionality in a kind of library, which could be yet
  a other tool
• platform independent - if not, it has to be Linux compatible at the
  very least as it will mostly run on CI jobs
• multi-programming-language support - each tool could use a different
  language
• plumbing through CLI interfaces
• to have a kind of comfortable managing interface to list, update, add
  and remove tools in any OSH documentation repo
• tools being git repos, and added to the OSH doc repo as git sub-modules

... but I am open for a completely different idea as well.
It would be especially cool, if a system that fits in here would already
exist of course.

Any ideas/inspirations/... ?