Developers Handbook - intended scope & direction?

[doia]

I’m tinkering with the new Developers Handbook and thinking about content, design, structure and all that stuff. I would like to have some information and thoughts from the core project maintainers (@chennes, @sliptonic, @yorik, @wandererfan just to name the contributors to the GitHub project) about the intended goal of this new project.

Currently the site is a bunch of articles, partially copied from the Wiki, partially with additional information. The design is a basic Jekyll theme which IMV lacks some functionality and style. If have read the introductionary blog post, yet some questions remain open:

- What is the intended scope & direction with this site?
- Is it a replacement of the Wiki? Is it a supplement?
- Are you open for design proposals, maybe using another Jekyll theme? What direction do you like to go?
- How do you see the structure within the wider FreeCAD eco system?

I personally like the move from a Wiki to an open repository. Mainly that changes are more transparent and controlled (if you have an active maintainer) and the workflow is more developer like. The main con so far is that there is no translation available (personally not a red flag for me, as I read most stuff in English anyways), which can surely be integrated somehow.

There are other good examples of developer centric documentation websites. As you may know, Blender also has a kind of a Developer Hub at https://developer.blender.org, which acts as a starting / welcome page for developers and links out to other parts of the developer documentation. All of them under the same header, which makes context switching easy and connects the different parts very well.

[sliptonic]

I’m tinkering with the new Developers Handbook and thinking about content, design, structure and all that stuff. I would like to have some information and thoughts from the core project maintainers (@chennes, @sliptonic, @yorik, @wandererfan just to name the contributors to the GitHub project) about the intended goal of this new project.

Awesome! Thanks for posting. Great questions. Here's my take:

- What is the intended scope & direction with this site?

The idea is growing and changing. It started from the need for two new documents: The roadmap and the stylebook. The idea is to put a stake in the ground about where the project is going. To give some solid guidelines for development goals. The roadmap should help us set priorities. The stylebook should help us normalize the user experience over time. The other documents seemed like a natural fit.

- Is it a replacement of the Wiki? Is it a supplement?

Right now the wiki serves two purposes. It's both end-user documentation and also a collection of 'stuff' meant for developers. IMHO, trying to do both in one place means neither one is great.

We've already talked about replacing the aging wiki with a more modern documentation system. In fact, we have a GSoC project focused on that. I would suggest that migrating away from the wiki would be a good time to create two separate resources; one for developers and one for end-users.

Maybe this handbook becomes part of the developers documentation at that time or maybe not. I don't know. For now, I'm satisfied to see if this kind of information presented in this format is useful. Will it help us get more contributors, get better contributions, and get them merged quicker.

- Are you open for design proposals, maybe using another Jekyll theme? What direction do you like to go?

Hell yes! Focus on usability. The front page should be limited to no more than 5-7 items. No huge laundry list here. This document should communicate the collective vision of the project. If it is beautiful and easy to use, all the better.

- How do you see the structure within the wider FreeCAD eco system?

Besides what I said above, I think it is 'Evolving'. We don't have to get it right the first time out. Let's iterate on it and keep what works.
I've become acquainted with the 'Gitlab Hanbook-first' concept. I'm a convert. It's really an important idea. If someone asks a question, the answer should be a link to the relevant handbook page. If the page doesn't exist, you write it and send them the link. The wiki (and future documentation) is ideal for documenting the application. It doesn't work as well for documenting how the community functions. For that, a handbook works better.

I personally like the move from a Wiki to an open repository. Mainly that changes are more transparent and controlled (if you have an active maintainer) and the workflow is more developer like. The main con so far is that there is no translation available (personally not a red flag for me, as I read most stuff in English anyways), which can surely be integrated somehow.

Agreed. Since we're writing in markdown, it would be pretty easy to move to something like docusaurus or similar tools that provide translation support.

There are other good examples of developer centric documentation websites. As you may know, Blender also has a kind of a Developer Hub at https://developer.blender.org, which acts as a starting / welcome page for developers and links out to other parts of the developer documentation. All of them under the same header, which makes context switching easy and connects the different parts very well.

Our roadmap document was absolutely inspired by Blender's equivalent. When you see something that works well, borrow it!

[andrecaldas]

Wow!!! I didn't know about this developers guide. I will stop everything I am doing and read it!

Sorry to hijack the post... but I'd like to suggest that a link to this handbook be pinned here at the "Developers corner".

[doia]

@sliptonic Thank you for the insight. Might want to add this to an About page to the DevBook.

Thanks as well for the link to the GitLab Handbook First approach. I have seen this already earlier, but forgot about it. I especially agree with the statement that Wikis don‘t scale.

So the main take aways for me are:
- collect the deeply buried knowledge of the forum and bring it into a central documentation
- make this documentation easier and more developer like to edit
- clear distinction between user and developer documentation -> these are two different focus groups
- overall the universal goal of a unification of the currently very fragmentated web presence of the FC eco system

In the tradition of your survey of the assembly workbenches I would say there are three main task to make this a concentrated effort:

Where do we stand?
What do we want? -> What is the desired structure and overall look off a DevBook?
And how do we get there?

I started with a collection of all the openly accessible web pages of the FC project and will post a summary in a future post.

[doia]

So, what do we have in terms of openly accessible web pages of the FreeCAD project? I made a quick overview what's live:

Overview of publicly available websites of the FreeCAD project

FC-websites-April-2023.jpg (510.66 KiB) Viewed 1544 times

freecad.org - FreeCADs main website
- the source code for this website is located under https://github.com/FreeCAD/FreeCAD-Homepage
- PHP based website, translation done via Crowding, which is occasionally loaded into the site
- my suggestion: migrate to a static webpage?

blog.freecad.org - a (very) basic blog about the latest FC related news
- source code? <- this is very intransparent for an open source project IMV
- lacks an archive list to easily find older post, reader has to scroll to the end and visit multiple pages to reach earlier posts

forum.freecad.org - the main FreeCAD forum
- based on phpBB
- basic themes are available, but overall style looks very old fashioned
- no possibility to write posts in markdown style
- the search functionality is a PITA straight from the books IMV
- I don't know a lot about forum software, but I'm sure there are better ones out there

github.com/FreeCAD - all the FreeCAD source code

gitlab.com/freecad - the FreeCAD source code mirrored on GitLab, but mostly outdated

fpa.freecad.org - website for the FreeCAD FPA
- Jekyll generated static website, hosted via Github?
- very basic design, but ok for the purpose, WiP

wiki.freecad.org - the FreeCAD wiki
- classic Wiki, used for users and developers alike
- here i like to mention that Wikis don‘t scale.

freecad.github.io/DevelopersHandbook - the newly started FC Developers Handbook
- source under https://github.com/FreeCAD/DevelopersHandbook
- Jekyll generated static website, hosted on Github
- active WiP, needs more structure
- my take: maybe change the URL to developer.freecad.org/handbook to make it consistent with other FC websites

freecad.github.io/SourceDoc - the Doxygen generated source code documentation
- source at https://github.com/FreeCAD/SourceDoc
- outdated, last commit August 2022

There are also a lot (!) of dead-end projects regarding documentation and blogs in the FreeCAD GitHub repo. These are very confusing in finding source code for current project websites. I would suggest setting these repos to Read-only mode and mark them as obsolete (change the repo name as well to clear the used namespace):

github.com/FreeCAD/freecad.github.io - old FreeCAD Development blog
- hosted under https://freecad.github.io
- inactive repo for a static website build with the Nikola
- has only contributions by forum member , the latest made in March 2019
- my suggestion: make a screenshot on archive.org and stop hosting, clear the used domain space

github.com/FreeCAD/FreeCAD-blog
- secondary FreeCAD blog source code for the aforementioned Developer blog, seems to be some precedessor
- last commit from March 2019 mostly from forum member @kkremitzki

github.com/FreeCAD/FreeCAD-Doc
- some copy from the Wiki?, generated with Python scripts
- massively outdated

freecad.github.io/API
- source at https://github.com/FreeCAD/API
- some older output from Doxygen, but mostly broken
- my suggestion: delete this repo, it is confusing and the result is autogenerated anyways

[matthiaswm]

tl;dr: When I tried to write some C++ code for FreeCAD, it was not so much the missing documentation of the internals. I had and still have big issues compiling FreeCAD on MacOS in a way so that I can doe meaningful development by setting breakpoints and inspecting variables, preferably from within Xcode.

More details:

I spent weeks to finally build FreeCAD on M1 from source. At the end, I ran out of energy, wrote the QuickLook code that is external, and gave up.

Maybe things are better on the Linux and Windows side of development, but for me personally, the very first chapter would explain how to compile for every platform. On MacOS, there are two ways to build, Homebrew and Docker. Both versions seem to mostly pull binaries, and generate libraries through fixup scripts. The CMake part of it does not allow to build with the Xcode generator. If building fails, diving deep will reveal issues with the Qt Python wrappers, version collisions in brew, and unlinked libraries. This is made even more difficult by Homebrew having changed their directory structure, so all the hardcoded paths don't work anymore on M1 MacOS.

[Syres]

I had and still have big issues compiling FreeCAD on MacOS in a way so that I can doe meaningful development by setting breakpoints and inspecting variables, preferably from within Xcode.

See https://github.com/oursland/FreeCAD-Build-Notes @oursland is a member of the forum

[oursland]

@matthiaswm @Syres

Please take a look at my build notes (https://github.com/oursland/FreeCAD-Build-Notes) to get a local development environment configured with support for debugging of C++ and Python code. The conda environment configuration changes have been merged into the FreeCAD repository, and I have updated the guide to reflect this.

Conda is used to perform the weekly builds, and I believe the release builds as well. When I get time I'll see if I can update the development guide and wiki for all three environments to provide instructions on using Conda, with the aim of providing a consistent build environment across platforms to improve developer experience.

My guide is geared towards Visual Studio Code as a cross-platform development IDE, but CMake can generate build files suitable for Xcode. I have no experience with using Xcode, so I cannot be much help. I believe that once you get the proper dependencies installed and configured, building and debugging within Xcode should be relatively straightforward.

One thing to note is that you will need to ensure that the compiler and libraries used to build are all the ones installed in the conda environment. The reason is that conda installs it's own version of libc++ and the macOS frameworks. If you mix-and-match the host-local libc++ and the conda installed libc++, you will get very bizarre errors at runtime. This lesson cost me two weeks of development.

[matthiaswm]

@oursland thank you for the link and the changes. I will dive into that next week and give it another try.

[matthiaswm]

@oursland @Syres Thank you. The process worked very well and I was able to set breakpoints and single-step. Awesome!

As an aside (it still built just fine):

Following https://github.com/oursland/FreeCAD-Build-Notes

at step 3: Install conda environment for FreeCAD, the last command failed:

conda devenv -f conda/environment.devenv.yml

with

Preparing transaction: done
Verifying transaction: done
Executing transaction: done
Installing pip dependencies: - Ran pip subprocess with arguments:
['/Users/matt/dev/FreeCAD.next/FreeCAD/.conda/freecad/bin/python', '-m', 'pip', 'install', '-U', '-r', '/Users/matt/dev/FreeCAD.next/FreeCAD/conda/condaenv.3ejy1l6s.requirements.txt', '--exists-action=b']
Pip subprocess output:

Pip subprocess error:

failed

CondaEnvException: Pip failed