Improve Documentation

[PhoneDroid]

Did a bunch of work, the only things I didn't
really do anything for was the Usage / Tutorial.
( You know it best, I'd encourage you to document
the various workflows someone might do as examples )

Changes

• Added separate addon manager specific Overview document
• Sorted media
• Replaced media with higher quality versions
• Added sun path animation ( webp default & gif version for the addon manager )
• Removed manual addon installation instructions, that shouldn't be recommended now that it will be automatically done via the addon manager
• Linked documentation folder as entry point for manifest documentation
• Described Radiance setup process

[Francisco-Rosa]

Thank you, it was truly a significant undertaking.

Questions and suggestions:

. Location of the folder containing the additional Python packages.

Where will the add manager install the folder with the ladybug libraries? This may require correcting the search for this folder in SunProperties.py.

. Radiance

I verified that the adjustments with flatseal do not solve the problem.

When Radiance is needed, it is first searched for in the "ladybug_tools" folder. For versions with installer, AppImage, and Flatpak, the path is ~/ladybug_tools. For the Snap version, the path varies, and it is necessary to first check where FC will create this folder. To do this, you will need to enter the FreeCAD Python console and type:

import ladybug.config as lb_config
rad_path = lb_config.folders.ladybug_tools_folder
print(f"{rad_path}")

. Automated Radiance installation

I will need to leave the eventual use of the Python wheel for later. For now, I prefer the manual instructions.

. README.md

Regarding the entire README.md redesign, since it's extensive, I think it's best to do it first in "updates" before "main," so we can test and modify it without compromising the workbench's functionality. The Solar updates GitHub repository has already been updated for this, but I don't know how to modify this PR to do this.

[PhoneDroid]

@Francisco-Rosa

. Location of the folder containing the additional Python packages.

I'm not quite sure what that logic is good for, any package you specify as a dependency - and is on the allow list - will automatically be installed by the addon manager.

While developing you might have to put them into freecads additional packages folder yourself, but normal users don't.

. Radiance
I'll adjust the docs then

. Automated Radiance installation
Ok, again in that case I'd recommend adding some UI with instructions and disabling the functionality that can't be used

. README.md

To clarify, the README isn't shown in the addon manager anymore, I've
created a dedicated file for that, that should only ever contain content
relevant to users of the addon, not everything related to the repository:
https://github.com/PhoneDroid/Addon-Solar/blob/Improve-Documentation/Resources/Documents/Overview.md

without compromising the workbench's functionality.
Not sure what you mean, the addon isn't live nor can the overview influence functionality?

The Solar updates GitHub repository

Repository? I couldn't find a separate repo, do you mean the updates branch?
I can change this PR to point there, but again it's not live yet, so I'm not sure it's necessary ..

[PhoneDroid]

Updated the installation instructions.

[Francisco-Rosa]

Repository? I couldn't find a separate repo, do you mean the updates branch?

Yes, updates branch.

I can change this PR to point there, but again it's not live yet, so I'm not sure it's necessary ..

Please, do it.

[PhoneDroid]

@Francisco-Rosa Done

[Francisco-Rosa]

Thank you. I made some changes regarding the Radiance installation. I remind you that flatseal is not effective in accessing the ladybug_tools folder, so I removed it from the instructions. I didn't understand why you removed the images and video indication from the usage examples. They are very illustrative. The main reason for using "updates" is to simulate the installation of ladybug packages via the addon manager. While the functionality is not fully guaranteed, the manual installation version of "main" will always remain. Therefore, the next important step is to test the workbench installation with the addon manager. Currently, I am locating the AdditionalPythonPackages folder in /.local/share/FreeCAD/Mod/Solar/freecad/Solar/. How will the addon manager act on this? It's still not clear to me. On Saturday, December 27, 2025 at 09:52:46 AM GMT-3, ᴩʜᴏɴᴇᴅʀᴏɪᴅ ***@***.***> wrote: PhoneDroid left a comment (Francisco-Rosa/Solar#13) @Francisco-Rosa Done — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[PhoneDroid]

@Francisco-Rosa

Right, I misunderstood your response about Flatseal.

The video is still there, it's in the tutorial section.

Using a separate branch for preview in the addon manager
is great, but what do you mean by:
While the functionality is not fully guaranteed
The addon manager will install those just fine ..?

Therefore, the next important step is to test the workbench installation with the addon manager. Currently, I am locating the AdditionalPythonPackages folder in /.local/share/FreeCAD/Mod/Solar/freecad/Solar/.

Wdym, Python packages are installed at <FreeCAD Data Folder>/AdditionalPythonPackages/<Pyhon Version>/,
it should never be located within an addon, if you are experiencing that, it sound like a bug ..

[Francisco-Rosa]

The AdditionalPythonPackages folder will be installed along with the Macro, Material, and Mod folders (at FreeCAD.getUserAppDataDir()). So, if another workbench needs other Python packages, those will also be installed there, right?  "Using a separate branch for preview in the addon manager is great, but what do you mean by: While the functionality is not fully guaranteed The addon manager will install those just fine ..?"I didn't know it, I have never used a workbench with additional package installation via addon manager. I have configured the SunProperties.py to find the packages in another location. I will have to modify this. On Sunday, December 28, 2025 at 10:39:59 AM GMT-3, ᴩʜᴏɴᴇᴅʀᴏɪᴅ ***@***.***> wrote: PhoneDroid left a comment (Francisco-Rosa/Solar#13) @Francisco-Rosa Right, I misunderstood your response about Flatseal. The video is still there, it's in the tutorial section. Using a separate branch for preview in the addon manager is great, but what do you mean by: While the functionality is not fully guaranteed The addon manager will install those just fine ..? Therefore, the next important step is to test the workbench installation with the addon manager. Currently, I am locating the AdditionalPythonPackages folder in /.local/share/FreeCAD/Mod/Solar/freecad/Solar/. Wdym, Python packages are installed at <FreeCAD Data Folder>/AdditionalPythonPackages/<Pyhon Version>/, it should never be located within an addon, if you are experiencing that, it sound like a bug .. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[PhoneDroid]

I have configured the SunProperties.py to find the packages in another location. I will have to modify this.

You just have to import the package name, no
finding packages & dynamic importing needed.

from numpy import x

[PhoneDroid]

To clarify, when developing you might have to copy the package
into the additional packages folder yourself just because the
addon manager doesn't run on locally linked addons.

[Francisco-Rosa]

Ok.  To my knowledge, how does the add-on manager do this? On Sunday, December 28, 2025 at 07:21:12 PM GMT-3, ᴩʜᴏɴᴇᴅʀᴏɪᴅ ***@***.***> wrote: PhoneDroid left a comment (Francisco-Rosa/Solar#13) To clarify, when developing you might have to copy the package into the additional packages folder yourself just because the addon manager doesn't run on locally linked addons. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[PhoneDroid]

Not quite sure what you are asking.

The addon manager installs the dependencies specified in the manifest.

If they are Python packages they go into the additional packages folder and are imported like any other Python package.

If they are other Addons, they are installed into the Mod folder and exposed depending on the structure type.

[Francisco-Rosa]

The question was, where or how does the addon manager save the path to the additional package folder so that FC can find the files? Anyway, I think we can test the Solar bench installation now, right? On Monday, December 29, 2025 at 04:09:15 PM GMT-3, ᴩʜᴏɴᴇᴅʀᴏɪᴅ ***@***.***> wrote: PhoneDroid left a comment (Francisco-Rosa/Solar#13) Not quite sure what you are asking. The addon manager installs the dependencies specified in the manifest. If they are Python packages they go into the additional packages folder and are imported like any other Python package. If they are other Addons, they are installed into the Mod folder and exposed depending on the structure type. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[PhoneDroid]

I'm not familiar with the internals of the addon manager.

Not sure how that would be relevant to an addon anyways,
again you should never traverse the filesystem manually
for calling Python dependencies.

Anyway, I think we can test the Solar bench installation now, right?

If you intend to go live, you should merge the updates branch into main ..

Only after that you should bump the date & version
tags in the manifest and create a GitHub release.

[Francisco-Rosa]

This dynamic is "interesting," one question, one reprimand, another question, another reprimand. Is this how it is for everyone, or am I being given special treatment? Why do you think you can judge what others may or may not know? Curious! I request that you modify your attitude. By the way, yes, it is vitally important to know how the addon manager will indicate the path to ladybug. I won't do anything without understanding exactly how the process will work. After all, the workbench depends 100% on the Ladybug libraries.  I will try to understand, with or without your help. Until then, the workbench will remain with manual installation. On Tuesday, December 30, 2025 at 01:59:57 PM GMT-3, ᴩʜᴏɴᴇᴅʀᴏɪᴅ ***@***.***> wrote: PhoneDroid left a comment (Francisco-Rosa/Solar#13) I'm not familiar with the internals of the addon manager. Not sure how that would be relevant to an addon anyways, again you should never traverse the filesystem manually for calling Python dependencies. Anyway, I think we can test the Solar bench installation now, right? If you intend to go live, you should merge the updates branch into main .. Only after that you should bump the date & version tags in the manifest and create a GitHub release. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[PhoneDroid]

Are you using auto-translation, I don't see how my
responses could be seen as reprimand in English?

By the way, yes, it is vitally important to know how the addon manager will indicate the path to ladybug. I won't do anything without understanding exactly how the process will work.

You are free to study the source code of the
Addon Manager if you want to learn it's internals.

[Francisco-Rosa]

Okay. I'll describe the problem in the GitHub PR. Let's see if it's really a translation issue. On Wednesday, December 31, 2025 at 12:01:24 PM GMT-3, ᴩʜᴏɴᴇᴅʀᴏɪᴅ ***@***.***> wrote: PhoneDroid left a comment (Francisco-Rosa/Solar#13) Are you using auto-translation, I don't see how my responses could be seen as reprimand in English? By the way, yes, it is vitally important to know how the addon manager will indicate the path to ladybug. I won't do anything without understanding exactly how the process will work. You are free to study the source code of the Addon Manager if you want to learn it's internals. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[Francisco-Rosa]

After researching, I understand that the addon manager will use the same resources I've been using.

After all, the answer wasn't that difficult to provide. Go figure.

I will merge the "updates" into "main".

[Francisco-Rosa]

The workbench has only been available for installation via the addon manager since January 7th, as instructed, but it hasn't been included in its collection. Is that correct?

[PhoneDroid]

@Francisco-Rosa Sorry, wasn't on top it, I've
readied the catalog PR, it should be merged soon.