Update OSH Automated Documentation for FreeCAD 1.0

[pieterhijma]

Proposal description

The current version of OSH Automated Documentation (osh-autodoc) is not supported on FreeCAD 1.0 and the documentation is out-of-date (still mentioning that it requires a FreeCAD greater than 0.21.2). After having had many requests from users to do so, in this project, I would like to update the workbench for FreeCAD 1.0 and the latest weekly.

The most pressing issue is that geometry that is exported to SVG images is not placed correctly on the page (issue #60, issue #58).

I've also received comments on other subjects, such as

• installation procedure on Mac, Linux, and Windows
• unclarity on licensing.

Deliverables

• New release of the workbench that works on FreeCAD 1.0 and the latest weekly.
  • Fix SVG export
  • Fix all other 1.0 related issues.
• A new release of the PDF compiler.
  • This version is to be installed on Windows and Mac as well.
• Updated website/documentation:
  • Updated installation instructions for Linux,
  • Installation instructions for Windows and Mac,
  • Graphics on the website with a modern FreeCAD theme,
  • A more motivating example, and
  • Clarified licensing.
• Updated representation in the Addon Manager:
  • Update the README to render well in the Addon Manager,
  • Make sure the most relevant information for Addon Manager users is in the README,
  • Update the version in the Addon Manager.

Timeline

This will be carried out in a 3-month period between July and October. The stages are:

1. Fix 1.0 related issues
2. Test the software for issues
3. Use an improved example model for the website and test with that model.
4. Streamline installation procedure, also for Windows and Mac
5. Update the documentation

Risks and mitigation

The biggest risk for this work is fixing the SVG export, because it is currently not clear what has changed in version 1.0 to cause this issue. A mitigation is postprocessing the generated SVG image with Inkscape (something that the software is already capable of), but this would be a very unsatisfying solution.

Another risk is installing the PDF compiler on Windows and Mac. In principle, the code is highly portable, but I'm unfamiliar with Windows and Mac development. A mitigation is to provide a working docker image.

Compensation

I would like to carry out this work with for a total of 2000 EUR.

About you

My name is Pieter Hijma (pieterhijma on the forum and pieterhijma on GitHub). I'm an independent contractor (https://pieterhijma.net) and have finished FPA grants (Research Variant Parts) and have ongoing FPA grants: (C++ API documentation and Improve the User Experience for VarSets).

I'm one of the co-authors of osh-autodoc and currently the maintainer. Unfortunately, I haven't had the resources to work on osh-autodoc, so I hope that this grant enables me to update the software for FreeCAD 1.0.

[Reqrefusion]

It's nice to revisit your first project, but I think it would have been better for 1.1 rather than FreeCAD 1.0. It will probably work in the development version, though. $2000 seems like a very acceptable compensation. Good luck.

[chennes]

Thank you for your grant proposal: it is now under review for the Q2 2025 grant cycle. The technical review committee will present its analysis to the FPA in two weeks, at which point the FPA vote process will begin, concluding on or before 1 July 2025, at which point funding decisions will be announced. You are welcome to modify your proposal to accommodate feedback received from the community during that time.

[pieterhijma]

It's nice to revisit your first project, but I think it would have been better for 1.1 rather than FreeCAD 1.0. It will probably work in the development version, though. $2000 seems like a very acceptable compensation. Good luck.

Thanks for the feedback. If in the meantime 1.1 has come out, I will make sure it works with 1.0, 1.1 and the development version. If 1.1 hasn't come out at that time, I hope that supporting the latest weekly will automatically support 1.1. And if not the case, I anticipate that making it work on 1.1 is much easier than it is now to support 1.0. If that is the case, I don't need a grant to make it compatible with 1.1.

So, in short, 1.1 is covered as well I think.

[yorikvanhavre]

This is a good proposal, and, although it is mostly a "personal project", it would have an interesting and highly wanted impact on FreeCAD, which is basically test a large workflow. In that sense, it acts as a very big unit test. This is something we should have more.

[chennes]

Thank you again for your proposal. The FPA's discussions took longer than anticipated, so the final vote was delayed. That vote is open now, and I will update this issue with the results when they are available.

[Reqrefusion]

The FPA's vote on the Quarter 2 2025 grant proposals is complete, and this grant was selected for funding. Congratulations @pieterhijma

The technical committee believes that you will complete the project, however, it also considers that the project is in a niche area. Additionally, there are concerns regarding your other responsibilities. Nevertheless, FPA has full confidence that you will carry out all your tasks thoroughly and appropriately. FPA is striving to support developers in every possible area.

FPA wishes to be more in contact with those who receive grants. For this reason, it has authorized a member. Currently, I am the authorized member responsible for these grant relationships. I will try to stay in constant communication with you. You can specify your preferred communication channel via email or here if you wish. Until then, the official communication space we will use will be this issue.

It has nothing to do with you, but I think I should inform you. If you are missing for 90 days without providing any excuse, the grant will be removed from the FPA budget.

[pieterhijma]

@Reqrefusion, thank you for informing me and thanks to the FPA and technical committee for selecting this proposal! This channel is good for communications.

[pieterhijma]

An update from my side: I've started this project and have been working on the incorrect position of objects in exported SVGs. Curiously, this has changed since first reported (in #60: Geometry in saved SVG image is not on the page). I've also identified other issues along the way:

• #75: Export SVG shows grid
• #76: LayerInfo objects are not claimed as children in layer states

The planning of this project will differ a bit from what the description says. This project will span the coming three months, October to December.