Port FeynCalc documentation to markdown

[vsht]

Given that documentation builds via Wolfram Workbench (WWB) are becoming increasingly challenging, while the compatibility with the most recent Mathematica versions is not so good, we should better completely abandon Mathematica's Documentation Center.

Instead of organizing the documentation as a bunch of .nb files that are eventually compiled via WWB, we should port those notebooks to Markdown. This approach has multiple advantages

• The whole documentation can be kept in git-friendly .m-files, rather than verbose .nb-files.
• The HTML version of the documentation for the website can be created on the fly with Mathematica without employing WWB.
• When editing existing pages, only modified content needs to be regenerated, not the whole set of pages (as it is the case with WWB)
• M2MD is a simple and clearly structured package that we can adapt to our needs to generate HTML files.
• We are not limited to a particular version of MMa (currently I have to generate the documentation with Mma 10.4, as newer versions produce weird glitches)

The main disadvantages are that

• The look & feel won't match that of Wolfram documentation pages.
• Local FeynCalc documentation will have to be shipped separately (e.g. as a PDF file built with GitHub actions ), but there will be no FeynCalc pages in the Documentation Center anymore.

[vsht]

Jupyter-book could be a good alternative, given that the kernel sort of work with Jupyter notebook as a front end.

https://jupyterbook.org/intro.html

https://github.com/executablebooks

[HBelusca]

I'm wondering, whether it exists some script or whatever that could automate generation of .nb documentation from the more human-readable markdown files (kind of the reverse of what you are doing). That would hypothetically allow you to have all the advantages of the markdown, and then ideally not loose the Mathematica Doc center, while at the same time not worrying about writing the .nb yourself.

[vsht]

This should be feasible, but most likely would require a comparable level of maintenance as before.

The documentation center is very tricky to support and the amount effort needed to keep it working among multiple Mathematica versions is completely out of proportion to its practical usefulness. Furthermore, notebooks are not human-readable and seem to be almost designed to resist version control systems.

This is why I'm quite happy to get rid of documentation notebooks and the monstrous toolchain for evaluating them in favor of something as simple and plain as M2MD plus few shell scripts.

The plan is to use markdown files to replace https://feyncalc.github.io/FeynCalcBook/guide/FeynCalc.html (which is what most people seem to use to look up FeynCalc symbols) and to generate a LaTeX manual out of them (via pandoc).

[vsht]

Note to myself: Include some examples on using polarization sum related functions in D dimensions.

[vsht]

The new online documentation is now available

https://feyncalc.github.io/referenceDev

and can be easily kept synchronized to the .m-documentation using helper scripts

https://github.com/FeynCalc/feyncalc/tree/master/FeynCalc/DocumentationFiles/Scripts

The scripts also take care of the synchronization between the documentation and the usage messages of all public FeynCalc symbols.

The next milestone is to create a proper PDF manual and make it build automatically using GH actions.

[vsht]

Now that we have a working toolchain to generate the PDF documentation automatically

https://github.com/FeynCalc/latex-docker https://github.com/FeynCalc/feyncalc-manual

and place the PDF file here

https://github.com/FeynCalc/feyncalc-manual/releases/tag/dev-manual

this issue can be closed. Of course, there are still many improvements that need to be implemented, but I'm mostly content with the workflow as it is.