diff --git a/bestpractices/index.md b/bestpractices/index.md index a797de3..e9aeff2 100644 --- a/bestpractices/index.md +++ b/bestpractices/index.md @@ -16,9 +16,9 @@ as inspiration for the better future. If you are a developer and want to read what we consider as good code please consult practices mentioned below. These guidelines try to define what the good code is and how it should be written. -- For C++ see [C++ practices](./c++practices.md) -- For Python see [Python practices](./pythonpractices.md) +- For C++ see [C++ practices](./c++practices) +- For Python see [Python practices](./pythonpractices) ## For Reviewers For reviews it is good to have a set of concrete rules that are easy to follow. If you want to learn how to review code, or -simply want to learn how we check code please consult the [reviewer guide](./codereview.md). +simply want to learn how we check code please consult the [reviewer guide](./codereview). diff --git a/designguide/elements.md b/designguide/elements.md index cbc427b..f380c24 100644 --- a/designguide/elements.md +++ b/designguide/elements.md @@ -14,7 +14,7 @@ Toolbar management in complex technical software such as CAD poses unique challe - Inverse functions (example: functionally similar additive and subtractive operations) should be combined into single tools wherever practicable. Switching between inverse modes should be done with a boolean control such as a toggle/checkbox within the related TaskPanel rather than resulting in separate tools. It minimizes space on toolbars and simplifies icon development. -- In accordance with the [Pareto Principle](laws-of-ux.md#pareto-principle.md), where a group of related functions consist of one which covers a majority of cases, a Menu Button should be formed to group those related functions into a single toolbar slot. The most common or likely to be used function should be presented as the default from that group on the toolbar. +- In accordance with the [Pareto Principle](./laws-of-ux.md#pareto-principle), where a group of related functions consist of one which covers a majority of cases, a Menu Button should be formed to group those related functions into a single toolbar slot. The most common or likely to be used function should be presented as the default from that group on the toolbar. - Toolbars should be broken into logical groupings, both visually(iconography), and functionally. Avoid use of many specialized toolbars in favor of more moderate sized toolbars. ie. one for basic functionality, and one for advanced. (80/20 rule helps here as well. Ideally there would be no more than 3 QToolBars in horizontal orientation or 2 toolbars in a vertical. Those are not hard requirements however. @@ -32,17 +32,17 @@ These are the dockable panels that typically reside docked to the left, right or #### Task Panels: -These panels are a quintessential component of FreeCAD's interface. A task panel is the means by which a user interacts with the current task being performed. Ranging from controlling sketch elements, defining parameters for a feature such as a Chamfer or set up parameters for CNC machining. These critical components **must** be uniform in both layout and sizing. A default width, in accordance with the UI [zones and layout](zones.md) definitions is established at 360 pixels. +These panels are a quintessential component of FreeCAD's interface. A task panel is the means by which a user interacts with the current task being performed. Ranging from controlling sketch elements, defining parameters for a feature such as a Chamfer or set up parameters for CNC machining. These critical components **must** be uniform in both layout and sizing. A default width, in accordance with the UI [zones and layout](./zones) definitions is established at 360 pixels. Here are general guidelines to be followed for a task panel: - "Ok" and "Cancel" buttons *shall* be located at the top of each panel with a centered alignment.\ Alternative button configurations are inconsistent and not acceptable. -- Minimize the width of the panel as much as possible through good use of space, arrangement of widgets, and [naming](naming.md). +- Minimize the width of the panel as much as possible through good use of space, arrangement of widgets, and [naming](./naming). -- Developers should use the appropriate [interactive control](interactive.md) widgets to ensure a consistent experience throughout +- Developers should use the appropriate [interactive control](./interactive) widgets to ensure a consistent experience throughout - Task Panels can potentially include enormous amounts of information and advanced settings/controls. Utilizing FreeCAD's custom [QSInt](https://freecad.github.io/SourceDoc/d9/d11/namespaceQSint.html) widget class, which provides a 'rolling up' of portions of the panel, is encouraged. Follow the [80/20 rule](laws-of-ux.md#pareto-principle), and by default only expose the most commonly needed controls/data to avoid overwhelming users with information/settings when they are not needed. This allows the user to expand more advanced settings, controls or information when the need arises. -[Return to Design Guide Main Page](index.md) +[Return to Design Guide Main Page](.) diff --git a/designguide/glossary.md b/designguide/glossary.md index 81238a1..80131bc 100644 --- a/designguide/glossary.md +++ b/designguide/glossary.md @@ -12,4 +12,4 @@ - **Design guidelines:** Guidelines are descriptive written and illustrated docs that demonstrate usage and behavior mainly through examples. They're the long-form discussion of specs that help designers and developers with problem-solving and decision-making. -[Return to Design Guide Main Page](index.md) +[Return to Design Guide Main Page](.) diff --git a/designguide/history-and-purpose.md b/designguide/history-and-purpose.md index 7c187dd..a46f526 100644 --- a/designguide/history-and-purpose.md +++ b/designguide/history-and-purpose.md @@ -6,4 +6,4 @@ This *Design Guide* is intended to present developers/designers a series of conc This guide is the product of a Design Working Group consisting of community members; ensuring decisions made regarding the User Interface and User Experience are consistent with the needs of people who actually use FreeCAD in both professional and hobbyist environments. This working group will also be involved with review of interface/experience related changes to FreeCAD to provide input to developers and maintainers regarding the merits and consistency of features which may impact interaction and/or workflows. -[Return to Design Guide Main Page](index.md) +[Return to Design Guide Main Page](.) diff --git a/designguide/index.md b/designguide/index.md index f068324..3e4605c 100644 --- a/designguide/index.md +++ b/designguide/index.md @@ -6,18 +6,18 @@ layout: default **This Design Guide is organized into the following sections** -- [History and Purpose](history-and-purpose.md) -- [Glossary of Terms](glossary.md) -- [Principles](principles.md) -- [Zones](zones.md) -- [Primary Elements](elements.md) -- [Input Hints Guidelines](input-hints.md) +- [History and Purpose](./history-and-purpose) +- [Glossary of Terms](./glossary) +- [Principles](./principles) +- [Zones](./zones) +- [Primary Elements](./elements) +- [Input Hints Guidelines](./input-hints) - Interactive Controls (Still under development) -- [Naming Convention](naming.md) +- [Naming Convention](./naming) - Colors and Accessibility (Still under development) - Theme/Styling (Still under development) - Icons/Art (Still under development) -- [FreeCAD Brand Guidelines](logo.md) +- [FreeCAD Brand Guidelines](./logo) *The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.txt).* diff --git a/designguide/laws-of-ux.md b/designguide/laws-of-ux.md index 7cce605..2d81bc9 100644 --- a/designguide/laws-of-ux.md +++ b/designguide/laws-of-ux.md @@ -207,4 +207,4 @@ [10 Jakob Nielsen's UI heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/) -[Return to Design Guide Main Page](index.md) +[Return to Design Guide Main Page](.) diff --git a/designguide/logo.md b/designguide/logo.md index af9a161..42d2911 100644 --- a/designguide/logo.md +++ b/designguide/logo.md @@ -107,4 +107,4 @@ We have made some examples of what **not** to do when using the logo: Download the [FreeCAD brand guidelines](../images/guidelines.pdf) as a PDF. These are also included in the logo kit at the top of the page. -[Return to Design Guide Main Page](index.md) +[Return to Design Guide Main Page](.) diff --git a/designguide/naming.md b/designguide/naming.md index 9a2d4fd..fcb8302 100644 --- a/designguide/naming.md +++ b/designguide/naming.md @@ -58,4 +58,4 @@ Lowercase only minor words that are three letters or fewer: - Command: `Save As…` - The function requires user input to function. - Command: `Addon Manager` - This is not a simple action, so no ellipsis. -[Return to Design Guide Main Page](index.md) +[Return to Design Guide Main Page](.) diff --git a/designguide/principles.md b/designguide/principles.md index 0db6a1c..8c002e4 100644 --- a/designguide/principles.md +++ b/designguide/principles.md @@ -1,9 +1,9 @@ # Principles -The following guiding principles are based on various established [Laws of UX outlined here](laws-of-ux.md). +The following guiding principles are based on various established [Laws of UX outlined here](./laws-of-ux). - Aesthetics - Not a replacement for good design, but helps compensate for minor flaws. Poor aesthetics can ruin an otherwise well designed functional flow.\ -([*Aesthetic-Usability Effect*](laws-of-ux.md#aesthetic-usability-effect)) +([*Aesthetic-Usability Effect*](./laws-of-ux.md#aesthetic-usability-effect)) - Avoid providing multiple ways to achieve the same goal within a singular workbench. Providing alternative methods seems like a benefit to the user but requires the user to process/understand why two methods exist and how they may differ.\ "There should be one-- and preferably only one --obvious way to do it."\ @@ -12,31 +12,31 @@ The following guiding principles are based on various established [Laws of UX ou - When implementing functionality which is common within other workbenches, a developer should make every effort to ensure behavior of those functions remains consistent with pre-existing implementations. - Attempt to make user interactions and software responses as fluid and quick as possible. Ideally below 400ms.\ -([*Doherty threshold*](laws-of-ux.md#doherty-threshold)) +([*Doherty threshold*](./laws-of-ux#doherty-threshold)) - Avoid making interactive elements too small. The size of elements should be large enough to prevent a majority of 'miss-clicks'.\ -([*Fitts's Law*](laws-of-ux.md#fitts-law)) +([*Fitts's Law*](./laws-of-ux#fitts-law)) - Travel distance between functions and related interactive elements should be minimized to reduce incidence of errors.\ -([*Fitts's Law*](laws-of-ux.md#fitts-law)) +([*Fitts's Law*](./laws-of-ux#fitts-law)) - Only expose the most common/likely settings or options a user may need by default. Advanced, or infrequently used controls should be hidden but readily accessible. This minimizes time required to make choices and increases efficiency.\ -([*Hick-Hyman Law*](laws-of-ux.md#hick-hyman-law)) +([*Hick-Hyman Law*](./laws-of-ux#hick-hyman-law)) - Minimize superfluous options in exchange for broadly effective defaults. Advanced preferences shall be accessible via the parameter editor instead of the preferences dialog.\ -([*Hick-Hyman Law*](laws-of-ux.md#hick-hyman-law)) +([*Hick-Hyman Law*](./laws-of-ux#hick-hyman-law)) - When implementing features or functions which are commonly found in other software, one should consider the method by which they function. Deviations from '*reasonably expected behavior*' shall be clearly justified.\ -([*Jakob's Law*](laws-of-ux.md#jakobs-law)) +([*Jakob's Law*](./laws-of-ux#jakobs-law)) - Behavior and element use across an application must remain consistent. Deviations shall be clearly justified.\ -([*Jakob's Law*](laws-of-ux.md#jakobs-law)) +([*Jakob's Law*](./laws-of-ux#jakobs-law)) - Ensure functions and options are grouped logically and not dispersed randomly.\ -([*Law of Common Region*](laws-of-ux.md#law-of-common-region)) +([*Law of Common Region*](./laws-of-ux#law-of-common-region)) - Proper organization of like functionality in close proximity together help users understand and organize information better.\ Related elements/functions should share similar visual symbology\ -([*Law of Proximity*](laws-of-ux.md#law-of-proximity) / [*Law of Uniform Connectedness*](laws-of-ux.md#law-of-uniform-connectedness)) +([*Law of Proximity*](./laws-of-ux#law-of-proximity) / [*Law of Uniform Connectedness*](./laws-of-ux#law-of-uniform-connectedness)) -[Return to Design Guide Main Page](index.md) +[Return to Design Guide Main Page](.) diff --git a/designguide/zones.md b/designguide/zones.md index ade2671..b8b83b7 100644 --- a/designguide/zones.md +++ b/designguide/zones.md @@ -32,4 +32,4 @@ Below is the notional zone layout of the FreeCAD user interface, specific sizes **Status Bar:** The status bar provides contextual information about the position of the mouse cursor in relation to the objects in the main view. This section of the UI is also home to some global controls within FreeCAD. They are "Notifications", "Navigation Style", and "Unit Selector". Developers shall not insert non-global elements or widgets into this area. -[Return to Design Guide Main Page](index.md) +[Return to Design Guide Main Page](.) diff --git a/gettingstarted/VSCode.md b/gettingstarted/VSCode.md index c1f7014..92883b1 100644 --- a/gettingstarted/VSCode.md +++ b/gettingstarted/VSCode.md @@ -120,7 +120,7 @@ Other useful extensions, recommended but not necessary are - ```donjayamanne.githistory```: Adds two buttons to the right-click menu: `git: view file history` and `git: view line history` -![](resources/extensions.png) +![](./resources/extensions.png) - On the very left you can see the `Todo-Tree` extension reporting `TODO`s and `FIXME` - On the left half you can see the `git graph` extension showing all the commits on different branches. You can click a commit to see exactly what was modified by it. diff --git a/gettingstarted/index.md b/gettingstarted/index.md index ad9da5a..bcacbec 100644 --- a/gettingstarted/index.md +++ b/gettingstarted/index.md @@ -20,7 +20,7 @@ Other combinations may work as well, these are just the ones that you will be ab ## Dependencies -See also [Dependencies](dependencies.md) +See also [Dependencies](./dependencies) FreeCAD depends on many other open source projects to provide the basic foundations of the program. There are many ways of installing these dependencies: for details and the complete list, see the following Wiki pages: @@ -65,11 +65,11 @@ The Visual Studio Installer may be used to install Visual Studio Community 2019 1. Open the Visual Studio Installer 2. Click `modify` for Visual Studio 2019. - ![Visual Studio 2019](resources/vs2019-modify.png) + ![Visual Studio 2019](./resources/vs2019-modify.png) 3. Make sure to select `Desktop development with C++` under the `Desktop & Mobile` section. Ensure that the necessary optional items are selected on the right. - ![vs2019-dev-C++](resources/vs2019-cpp.png) + ![vs2019-dev-C++](./resources/vs2019-cpp.png) ## Setting up for Development @@ -108,8 +108,8 @@ The Visual Studio Installer may be used to install Visual Studio Community 2019 ## Running and Debugging - - [Visual Studio Code](./VSCode.md) - - [CLion](./CLion.md) + - [Visual Studio Code](./VSCode) + - [CLion](./CLion) ## Submitting a PR diff --git a/index.md b/index.md index 2701428..1fcc22a 100644 --- a/index.md +++ b/index.md @@ -2,23 +2,23 @@ Welcome to the FreeCAD Developer's Guide! This is a work-in-progress, so please feel free to submit Issues and Pull Requests when you find areas that need work. -### [Roadmap](./roadmap/index.md) +### [Roadmap](./roadmap) Describes the broad objectives for FreeCAD Development -### [Getting Started](./gettingstarted/index.md) +### [Getting Started](./gettingstarted) How to set up a development environment to work on FreeCAD. -### [Design Guide](./designguide/index.md) +### [Design Guide](./designguide) Covers guidelines for User Experience, Interaction and Interface in FreeCAD. -### [Code Formatting Guide](./codeformatting/index.md) +### [Code Formatting Guide](./codeformatting) Covers the C++ and Python code formatting guidelines. -### [Good Practices / Code Review Guide](./bestpractices/index.md) +### [Good Practices / Code Review Guide](./bestpractices) Covers the C++ and Python code best practices and tips for code reviewers. -### [Maintainers Guide](./maintainersguide/index.md) +### [Maintainers Guide](./maintainersguide) Gives guidelines to maintainers about code reviews and merge procedures. -### [Technical Guide](./technical/index.md) +### [Technical Guide](./technical) A guide for developers learning their way around the FreeCAD codebase. diff --git a/maintainersguide/index.md b/maintainersguide/index.md index 6f3edd4..6189b6a 100644 --- a/maintainersguide/index.md +++ b/maintainersguide/index.md @@ -4,7 +4,7 @@ layout: default # Maintainers Guide -Guidelines for Maintainers regarding code review and merge procedures. Git can be [configured to make checking out and reviewing PRs easier](./git.md). +Guidelines for Maintainers regarding code review and merge procedures. Git can be [configured to make checking out and reviewing PRs easier](./git). ## The Team diff --git a/roadmap/index.md b/roadmap/index.md index 8677cd5..7e7b46e 100644 --- a/roadmap/index.md +++ b/roadmap/index.md @@ -10,13 +10,13 @@ The roadmap provides broad objectives for the direction of FreeCAD development. This document describes several high-level objectives for the FreeCAD project. Rather than being a laundry list of development tasks, it focuses on a small set of strategic initiatives that, if achieved, will move FreeCAD closer to an ideal future state. -You can read more about the [rationale for having a roadmap](rationale.md). +You can read more about the [rationale for having a roadmap](./rationale). This roadmap outlines broad strategic objectives. Code contributions from developers will always be evaluated on their merits but are more likely to receive timely attention and be successfully merged if they are consistent with the stated objectives of this roadmap. ## The "Next" Release -These objectives described here are very broad. Some of them are very ambitious and will take a long time to achieve. Others will never be fully achieved or 'done'. For that reason, it's helpful to pick a specific set of goals to focus on for the next release. [This page](next.md) broadly describes the major goals for the next release. +These objectives described here are very broad. Some of them are very ambitious and will take a long time to achieve. Others will never be fully achieved or 'done'. For that reason, it's helpful to pick a specific set of goals to focus on for the next release. [This page](./next) broadly describes the major goals for the next release. ### Objective: Model stability diff --git a/technical/CreatePythonBindingForCpp.md b/technical/CreatePythonBindingForCpp.md index 3ec0dbc..dbae829 100644 --- a/technical/CreatePythonBindingForCpp.md +++ b/technical/CreatePythonBindingForCpp.md @@ -158,5 +158,5 @@ There is a convention for return values from our C++/Python connections: * [https://forum.freecadweb.org/viewtopic.php?p##314796#p314617] * [https://forum.freecadweb.org/viewtopic.php?p##560639#p560639] Forum discussion: Adding Commands in Python to C++ Workbench * [https://forum.freecadweb.org/viewtopic.php?f##10&t##70750] Another forum thread -* (./Workbench creation.md) +* (./Workbench creation) * [https://github.com/FreeCAD/FreeCAD/commit/20b86e55b8dd1873f4c19e036d047528c9ff7f4e] Commit 20b86e5, exposing OCC's precision methods to Python diff --git a/technical/MajorRelease.md b/technical/MajorRelease.md index c17790a..95778e4 100644 --- a/technical/MajorRelease.md +++ b/technical/MajorRelease.md @@ -72,7 +72,7 @@ Any problems identified with the release candidate should be addressed via PRs m - Manually tag the release on the appropriate branch using semantic versioning for the tag name, e.g. "1.2.3". Launch the various build-creation tasks based on this tag. - Conda builds for all platforms - Manual compilation of a Windows LibPack-based binary and NSIS-created installer - - Sign and notarize the Mac OS Conda builds once they are complete (See [Code signing](./codesigning.md)) + - Sign and notarize the Mac OS Conda builds once they are complete (See [Code signing](./codesigning)) - (Future work) Sign the Windows builds - Create a new release on GitHub, this time marking the "Set as latest release" box and not marking it as a pre-release, and setting the release to use the tag created above. It's best to ensure all assets are attached prior to publication of the final release, so save the release as a draft as necessary until all builds are completed. The release contains a release announcement text that should be appropriate for the general user audience (not targeted at developers). - Prepare a packager's release files and alert the packagers. diff --git a/technical/ReleaseProcess.md b/technical/ReleaseProcess.md index 3844f96..1076fc8 100644 --- a/technical/ReleaseProcess.md +++ b/technical/ReleaseProcess.md @@ -16,5 +16,5 @@ Between major releases, bugs are occasionally found and repaired. These fixes ma Major and minor releases have slightly different processes. -- [Major Releases](./MajorRelease.md) -- [Minor Releases](./MinorRelease.md) +- [Major Releases](./MajorRelease) +- [Minor Releases](./MinorRelease) diff --git a/technical/index.md b/technical/index.md index 2a85fc5..74fd7d4 100644 --- a/technical/index.md +++ b/technical/index.md @@ -8,19 +8,19 @@ Technical information of interest to Contributors. ## The Basics -- [Developer's Glossary](./developerglossary.md) +- [Developer's Glossary](./developerglossary) -- [Source Tree Basics](./SourceTreeBasics.md) +- [Source Tree Basics](./SourceTreeBasics) -- [The Application Module](./TheApplicationModule.md) +- [The Application Module](./TheApplicationModule) - [The Source Code in More Depth](https://wiki.freecad.org/The_FreeCAD_source_code) -- [Writing Code for Translation](./translation.md) +- [Writing Code for Translation](./translation) -- [Automated Testing](./automated_testing.md) +- [Automated Testing](./automated_testing) -- [Dealing with Property Changes](./PropertyChanges.md) +- [Dealing with Property Changes](./PropertyChanges) - The FreeCAD developer's tool set: @@ -32,7 +32,7 @@ Technical information of interest to Contributors. - [Websites](./Websites) -- [Reference Library](./ReferenceLibrary.md) +- [Reference Library](./ReferenceLibrary) ## Modifying FreeCAD @@ -45,23 +45,23 @@ Technical information of interest to Contributors. - The [PowerUser's hub](https://wiki.freecad.org/Power_users_hub) in the FreeCAD wiki contains good information about Python scripting and workbench creation -- [Python stubs package](./PythonStubsPackage.md) +- [Python stubs package](./PythonStubsPackage) -- [Accessing User Preferences](./preferences.md) +- [Accessing User Preferences](./preferences) -- [Controlling Object Deletion](./ObjectDeletion.md) +- [Controlling Object Deletion](./ObjectDeletion) -- [Create a Python Binding for C++ Class](./CreatePythonBindingForCpp.md) +- [Create a Python Binding for C++ Class](./CreatePythonBindingForCpp) -- [Checklist for Adding a Feature to a Workbench in C++](./ChecklistForNewFeatureC++.md) +- [Checklist for Adding a Feature to a Workbench in C++](./ChecklistForNewFeatureC++) ## Release Management -- [Overview](./ReleaseProcess.md) +- [Overview](./ReleaseProcess) - - [Major Releases](./MajorRelease.md) - - [Minor Releases](./MinorRelease.md) - - [Building Release Packages](./ReleasePackages.md) + - [Major Releases](./MajorRelease) + - [Minor Releases](./MinorRelease) + - [Building Release Packages](./ReleasePackages) ## See Also