search

vermaseren / form

The FORM project for symbolic manipulation of very big expressions
GNU General Public License v3.0
982 stars 118 forks source link

Continuous integration document building? #310

Open tueda opened 5 years ago

tueda commented 5 years ago

Continuous integration is one of the modern practices in software development: most decent projects adopt it to improve their code quality. FORM already uses Travis CI for detecting software regression bugs.

On the other hand, reFORM uses Read the Docs to build its documentation (well, it haven't used CI for test purpose, though). It would be nice to have a similar framework to continuously build all the documentation of FORM for every commit. Read the Docs seems not to support LaTeX documents, so the easiest way would be:

vermaseren commented 5 years ago

This sounds very logical, but currently I have absolutely no time to study this further, let alone implement it. But for the future diagram generation I can make a separate documentation version that can be seen as a ’stand alone’ document. Most likely there will also be a publication.

On 7 Mar 2019, at 13:18, Takahiro Ueda notifications@github.com wrote:

Continuous integration is one of the modern practices in software development: most decent projects adopt it to improve their code quality. FORM already uses Travis CI https://travis-ci.org/vermaseren/form for detecting software regression bugs.

On the other hand, reFORM https://github.com/benruijl/reform uses Read the Docs https://readthedocs.org/ to build its documentation (well, it haven't used CI for test purpose, though). It would be nice to have a similar framework to continuously build all the documentation of FORM for every commit. Read the Docs seems not to support LaTeX documents, so the easiest way would be:

Build all the documents (User & Developer's manual, Doxygen documents) in HTML, PDF etc. on Travis CI. Indeed the User's manual in the past releases has been built in this way. Deploy the documents to a Git repository. The documents could be put in a branch of vermaseren/form https://github.com/vermaseren/form/ (we actually have a most-likely forgotten branch for the web site http://vermaseren.github.io/form/), but maybe less confusing to make a repository specialized for storing documentations. We keep documentations for the latest commit on the master branch and also those for release tags. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/vermaseren/form/issues/310, or mute the thread https://github.com/notifications/unsubscribe-auth/AFLxEuGjva4zh0uk6OHtZ_KMQvmuR6Fmks5vUQODgaJpZM4bjDbY.

tueda commented 5 years ago

Hi Jos, this must be rather straightforward, so I can try to construct a framework when I have time. (Perhaps after ACAT.) The question would be: which repository we will use. If we decide to create a repository, for example vermaseren/formdoc, then you need to press the "New repository" button and invite Ben, me and others for writing permission.

tueda commented 4 years ago

Here is an example of workflow code to automatically generate FORM documents with Github Actions and push them to another repository.

Documents generated:

Build log: https://github.com/tueda/form/runs/319015195

Each build should generate the above documents and upload them to the document repository (in the directory latest). For each release, we could copy the latest directory to each tag (e.g., v4.2.2) by hand, or maybe this could be also automatized.

It should be easy to set up the same thing for the main FORM repository. Probably, we need a new repository vermaseren/form-doc to store the documents.

tueda commented 2 weeks ago

Maybe we can simply put HTML/PDF document files created in the deploy workflow for the master branch to

i.e., the corresponding directory in the gh-pages branch.

(With GitHub Actions, pushing files to another branch on the same repository is quite straightforward.)

The same with

for the 4.3 branch and

for tag pushes.