Improve the FreeCAD API documentation

[drLite35]

Proposal description

1. To enhance the FreeCAD API documentation, several key improvements are proposed. Firstly, organizing the documentation involves creating a hierarchical structure for modules, facilitating easier navigation and comprehension. This includes segregating Python and C++ functionalities and providing comprehensive overview pages for each module, outlining all classes, functions, and significant features.

2. Secondly, enhancing docstrings is crucial. Ensuring uniformity and thoroughness across docstrings is essential. Focusing on providing vital details such as parameters, return types, exceptions, and practical usage examples will significantly improve readability and understanding.

3. Thirdly, updating the Doxygen configuration can enhance the documentation's visual appeal and usability. Enabling features like UML diagrams offers a graphical representation of relationships, while customizing the output using layout files and CSS improves overall readability and aesthetics.

4. Fourthly, automating documentation generation streamlines the process and ensures the latest documentation is readily available.

5. Lastly, regular maintenance and feedback mechanisms are crucial. Conducting periodic audits ensures documentation accuracy and completeness, while implementing a feedback mechanism allows users to provide valuable input for continual improvement. Regular updates reflecting codebase changes ensure that documentation remains current and relevant, fostering a robust and user-friendly resource for the FreeCAD community.

Deliverables

1. Initial Assessment Deliverables:

• Review report on current documentation structure.
• Summary of key pain points based on user and contributor feedback.
• Comparative analysis of documentation structures from successful projects.

2. Structuring Documentation Deliverables:

• Documented hierarchical module organization plan.
• Visual differentiation strategy for Python and C++ functionalities.
• Module overview pages outlining classes, functions, and key features.

3. Improving Readability Deliverables:

• Style guide document for consistent docstring formatting.
• Examples of well-documented classes and functions.
• Implementation plan for enforcing style guide through code reviews and automation.

4. Content Enhancement Deliverables:

• Detailed descriptions for each module, class, and function.
• Cross-referenced documentation utilizing Doxygen capabilities.
• Technical Improvements Deliverables:

5. Updated Doxygen configuration file (Doxyfile).

• Customization plan for improving readability with CSS and custom tags.

6. Feedback mechanism integrated into documentation site.
   • Contributor guide document with instructions for effective documentation.

Timeline

This projects should take around 20-22 weeks starting from June to October.

Week 1-2:

Resolve all Missing and empty API documentation issues. Analyze existing Doxygen docstrings and code structure. Evaluate Doxygen configuration settings for potential optimizations.

Week 3-4:

Develop templates for standardized Doxygen docstrings.

Week 5-6:

Analyze codebase to identify areas for better documentation organization. Implement structural modifications ensuring backward compatibility.

Week 7-8:

Evaluate existing tools/scripts for documentation enhancement. Develop and integrate custom tools/scripts into the workflow.

Week 9-10:

Customize new scripts as needed.

Week 11-12:

Customize Doxyfile configuration for optimized FreeCAD documentation output. Define custom snippets/macros for improved readability.

Week 13-14:

Test effectiveness of Doxygen configuration changes.

Week 15-16:

Plan unit testing for updated docstrings and code modifications.

Week 17-18:

Conduct unit testing for accuracy of updates. Perform integration testing for seamless documentation/code integration.

Week 19-20:

Gather feedback from beta testers/user groups on documentation usability.

Week 20-21:

Conduct final testing to address outstanding issues. Review and finalize documentation for more enhancements

Risks and mitigation

There are no foreseeable risks for this project. However, it's worth noting that until the end of July, I'll also be engaged in a GSOC project. Nevertheless, this won't pose any hindrance, as my summer break extends until August.

Compensation

I Would Like Compensation of 4000 USD , i.e around 800 USD Per Month as it will take around 5 Months to get this completed.

About you

Name: Anurag Singh Email: prinicipalquantum30@gmail.com GitHub Profile: Ovalelephant35

I have contributed to FreeCAD and have meticulously planned for the same while applying for GSOC. For further reference regarding all my PRs and contributions, please refer to this link. Additionally, you can find detailed plans and implementation strategies in the attached document FreeCAD_Oval (1).docx.

The plan aims to ensure that every function has a @brief summary, providing a concise description of its purpose. It includes detailed explanations for each function to offer context and usage guidelines. Moreover, the plan involves utilizing @param and @return tags comprehensively to describe function parameters and return values, among other enhancements. Below is an example of the proposed improved documentation structure:

Module Overview (Example) Module: Part Description: This module provides functionalities to create and manipulate geometric shapes. Classes:

Part::Feature: Represents a feature in the part. Part::Shape: Represents a geometric shape. Functions: createShape(parameters): Creates a new shape with the given parameters. exportShape(fileName): Exports the shape to the specified file. Thank you for your attention and consideration!

[drLite35]

Please review the proposal, @chennes, @yorikvanhavre, and FPA. Your feedback and suggestions are highly valued, and any changes or inputs you may have are greatly appreciated. Thank you very much!

[yorikvanhavre]

This is a valid proposal to me, and I believe it can fully go together with #4 . Ideally both should define a common nomenclature to be used further in all of FreeCAD.

I would also like to see if a markdown output could be produced, so the generated output could seamlessly integrate with a future, markdown-based version of our wiki documentation

[drLite35]

Thank you for your review, @yorikvanhavre.

Yes, Doxygen can be configured to generate documentation in Markdown format. Although Doxygen natively supports output formats like HTML, LaTeX, and RTF, either we can use a combination of Doxygen and additional tools to convert the generated XML output into Markdown and there are other several ways also possible that can be discussed.

@pieterhijma, please review the proposal and let me know where you'd like to start or provide your input on the plan of action. This will help us coordinate on the nomenclature and other details.

Thanks!

[pieterhijma]

@Ovalelephant35, I think this is a very nice proposal and as I said, I would love to collaborate on this important topic.

I recognize we already agree on @brief, @param, and @return. I believe it is important to collaborate and find an agreement on:

3. Improving Readability Deliverables:
   • Style guide document for consistent docstring formatting.
   • Examples of well-documented classes and functions.
   • Implementation plan for enforcing style guide through code reviews and automation.

Other topics to discuss and collaborate on are cross-referencing, how to create the split between Python/C++, improving the readability, and the contributor guide.

[drLite35]

@Ovalelephant35, I think this is a very nice proposal and as I said, I would love to collaborate on this important topic.

I recognize we already agree on @brief, @param, and @return. I believe it is important to collaborate and find an agreement on:

3. Improving Readability Deliverables:

• Style guide document for consistent docstring formatting.
• Examples of well-documented classes and functions.
• Implementation plan for enforcing style guide through code reviews and automation.

Other topics to discuss and collaborate on are cross-referencing, how to create the split between Python/C++, improving the readability, and the contributor guide.

Thanks, ok once FPA gives there opinion we can start working on it.

[macdroid53]

I'm all for better docs. I see the mention of docstrings. Will this include the Python api?

[drLite35]

@macdroid53 Yes, this includes keeping in mind that they have to be done in markdown based doc structure.

[chennes]

The FPA Grant Review Committee has evaluated this proposal, and supports funding it. This dovetails well with Grant Proposal #4, and both contributors have already indicated that they intend to collaborate on the work. It's work that few developers are interested in undertaking, and will benefit the entire community of FreeCAD developers (and ultimately users). I have forwarded this recommendation to the full FPA for voting.

[chennes]

The FPA has voted to approve this grant. Congratulations, @Ovalelephant35, and thank you for your proposal. Please reach out to wandererfan@freecad.org to set up your banking information.

[drLite35]

Thanks to FPA and everyone involved with for providing me this opportunity.