From 1c1876863405a33066e2403514f4f54503014ee4 Mon Sep 17 00:00:00 2001 From: Yorik van Havre Date: Mon, 16 Oct 2023 18:17:06 +0200 Subject: [PATCH] Merging the Help module (#11008) * Adding the Help module - fixes 10527, fixes #10512 * Aded Help to pre-commit * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .pre-commit-config.yaml | 1 + .../InitializeFreeCADBuildOptions.cmake | 1 + src/Mod/CMakeLists.txt | 4 + src/Mod/Help/CMakeLists.txt | 25 + src/Mod/Help/Help.py | 463 ++++++++++++++++++ src/Mod/Help/InitGui.py | 27 + src/Mod/Help/Resources/Help.qrc | 5 + src/Mod/Help/Resources/translations/Help.ts | 210 ++++++++ .../Help/Resources/translations/Help_en.qm | 1 + .../Help/Resources/translations/Help_en.ts | 210 ++++++++ src/Mod/Help/default.css | 19 + src/Mod/Help/dlgPreferencesHelp.ui | 279 +++++++++++ src/Tools/updatecrowdin.py | 2 + src/Tools/updatets.py | 5 + 14 files changed, 1252 insertions(+) create mode 100644 src/Mod/Help/CMakeLists.txt create mode 100644 src/Mod/Help/Help.py create mode 100644 src/Mod/Help/InitGui.py create mode 100644 src/Mod/Help/Resources/Help.qrc create mode 100644 src/Mod/Help/Resources/translations/Help.ts create mode 100644 src/Mod/Help/Resources/translations/Help_en.qm create mode 100644 src/Mod/Help/Resources/translations/Help_en.ts create mode 100644 src/Mod/Help/default.css create mode 100644 src/Mod/Help/dlgPreferencesHelp.ui diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index eaa020b5b694..8553a273f7f4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -12,6 +12,7 @@ files: | src/Mod/Drawing| src/Mod/Fem/App| src/Mod/Fem/Gui| + src/Mod/Help| src/Mod/Import| src/Mod/Inspection| src/Mod/JtReader| diff --git a/cMake/FreeCAD_Helpers/InitializeFreeCADBuildOptions.cmake b/cMake/FreeCAD_Helpers/InitializeFreeCADBuildOptions.cmake index 15ea3f66808b..2e70b36152f6 100644 --- a/cMake/FreeCAD_Helpers/InitializeFreeCADBuildOptions.cmake +++ b/cMake/FreeCAD_Helpers/InitializeFreeCADBuildOptions.cmake @@ -106,6 +106,7 @@ macro(InitializeFreeCADBuildOptions) option(BUILD_ARCH "Build the FreeCAD Architecture module" ON) option(BUILD_DRAFT "Build the FreeCAD draft module" ON) option(BUILD_DRAWING "Build the FreeCAD drawing module" OFF) + option(BUILD_HELP "Build the FreeCAD help module" ON) option(BUILD_IDF "Build the FreeCAD idf module" ON) option(BUILD_IMPORT "Build the FreeCAD import module" ON) option(BUILD_INSPECTION "Build the FreeCAD inspection module" ON) diff --git a/src/Mod/CMakeLists.txt b/src/Mod/CMakeLists.txt index 4bef5ea39603..5ca5e95a804e 100644 --- a/src/Mod/CMakeLists.txt +++ b/src/Mod/CMakeLists.txt @@ -26,6 +26,10 @@ if(BUILD_FEM) add_subdirectory(Fem) endif(BUILD_FEM) +if(BUILD_HELP) + add_subdirectory(Help) +endif(BUILD_HELP) + if(BUILD_IDF) add_subdirectory(Idf) endif(BUILD_IDF) diff --git a/src/Mod/Help/CMakeLists.txt b/src/Mod/Help/CMakeLists.txt new file mode 100644 index 000000000000..4c4a67d95d05 --- /dev/null +++ b/src/Mod/Help/CMakeLists.txt @@ -0,0 +1,25 @@ +IF (BUILD_GUI) + PYSIDE_WRAP_RC(Help_QRC_SRCS Resources/Help.qrc) +ENDIF (BUILD_GUI) + +SET(Help_SRCS + InitGui.py + default.css + Help.py + dlgPreferencesHelp.ui +) + +SOURCE_GROUP("" FILES ${Help_SRCS}) + +ADD_CUSTOM_TARGET(Help ALL SOURCES ${Help_SRCS} ${Help_QRC_SRCS}) + +fc_copy_sources(Help "${CMAKE_BINARY_DIR}/Mod/Help" ${Help_SRCS}) + +IF (BUILD_GUI) + fc_target_copy_resource(Help + ${CMAKE_CURRENT_BINARY_DIR} + ${CMAKE_BINARY_DIR}/Mod/Help + Help_rc.py) +ENDIF (BUILD_GUI) + +INSTALL(FILES ${Help_SRCS} ${Help_QRC_SRCS} DESTINATION Mod/Help) diff --git a/src/Mod/Help/Help.py b/src/Mod/Help/Help.py new file mode 100644 index 000000000000..aa07f27da51f --- /dev/null +++ b/src/Mod/Help/Help.py @@ -0,0 +1,463 @@ +# -*- coding: utf-8 -*- + +# *************************************************************************** +# * Copyright (c) 2021 Yorik van Havre * +# * * +# * This program is free software; you can redistribute it and/or modify * +# * it under the terms of the GNU Lesser General Public License (LGPL) * +# * as published by the Free Software Foundation; either version 2 of * +# * the License, or (at your option) any later version. * +# * for detail see the LICENCE text file. * +# * * +# * This program is distributed in the hope that it will be useful, * +# * but WITHOUT ANY WARRANTY; without even the implied warranty of * +# * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * +# * GNU Library General Public License for more details. * +# * * +# * You should have received a copy of the GNU Library General Public * +# * License along with this program; if not, write to the Free Software * +# * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * +# * USA * +# * * +# *************************************************************************** + +""" +Provide tools to access the FreeCAD documentation. + +The main usage is using the "show" function. It can retrieve an URL, +a local file (markdown or html), or find a page automatically from +the settings set under Preferences->General->Help. + +It doesn't matter what you give, the system will recognize if the contents are +HTML or Markdown and render it appropriately. + +Basic usage: + + import Help + Help.show("Draft Line") + Help.show("Draft_Line") # works with spaces or underscores + Help.show("https://wiki.freecadweb.org/Draft_Line") + Help.show("https://gitlab.com/freecad/FreeCAD-documentation/-/raw/main/wiki/Draft_Line.md") + Help.show("/home/myUser/.FreeCAD/Documentation/Draft_Line.md") + Help.show("http://myserver.com/myfolder/Draft_Line.html") + +Preferences keys (in "User parameter:BaseApp/Preferences/Mod/Help"): + + optionBrowser/optionTab/optionDialog (bool): Where to open the help dialog + optionOnline/optionOffline (bool): where to fetch the documentation from + URL (string): online location + Location (string): offline location + Suffix (string): a suffix to add to the URL, ex: /fr + StyleSheet (string): optional CSS stylesheet to style the output +""" + +import os +import FreeCAD + + +translate = FreeCAD.Qt.translate +QT_TRANSLATE_NOOP = FreeCAD.Qt.QT_TRANSLATE_NOOP + +# texts and icons +WIKI_URL = "https://wiki.freecad.org" +MD_RAW_URL = "https://raw.githubusercontent.com/FreeCAD/FreeCAD-documentation/main/wiki" +MD_RENDERED_URL = "https://github.com/FreeCAD/FreeCAD-documentation/blob/main/wiki" +MD_TRANSLATIONS_FOLDER = "translations" +ERRORTXT = translate( + "Help", + "Contents for this page could not be retrieved. Please check settings under menu Edit -> Preferences -> General -> Help", +) +LOCTXT = translate( + "Help", + "Help files location could not be determined. Please check settings under menu Edit -> Preferences -> General -> Help", +) +LOGTXT = translate( + "Help", + "PySide QtWebEngineWidgets module is not available. Help rendering is done with the Web module", +) +CONVERTTXT = translate( + "Help", + "There is no markdown renderer installed on your system, so this help page is rendered as is. Please install the markdown or pandoc python modules to improve the rendering of this page.", +) +PREFS = FreeCAD.ParamGet("User parameter:BaseApp/Preferences/Mod/Help") +ICON = ":/icons/help-browser.svg" + + +def show(page, view=None, conv=None): + """ + show(page,view=None, conv=None): + Opens a help viewer and shows the given help page. + The given help page can be a URL pointing to a markdown or HTML file, + a name page / command name, or a file path pointing to a markdown + or HTML file. If view is given (an instance of openBrowserHTML.HelpPage or + any other object with a 'setHtml()' method), the page will be + rendered there, otherwise a new tab/widget will be created according to + preferences settings. If conv is given (markdown, pandoc, github, builtin or + none), the corresponding markdown conversion method is used. Otherwise, the + module will use the best available. + In non-GUI mode, this function simply outputs the markdown or HTML text. + """ + + page = underscore_page(page) + location = get_location(page) + FreeCAD.Console.PrintLog("Help: opening " + location + "\n") + if not location: + FreeCAD.Console.PrintError(LOCTXT + "\n") + return + md = get_contents(location) + html = convert(md, conv) + baseurl = get_uri(location) + pagename = os.path.basename(page.replace("_", " ").replace(".md", "")) + title = translate("Help", "Help") + ": " + pagename + if FreeCAD.GuiUp: + if PREFS.GetBool("optionBrowser", False): # desktop web browser + show_browser(location) + elif PREFS.GetBool("optionDialog", False): # floating dock window + show_dialog(html, baseurl, title, view) + else: # MDI tab - default + show_tab(html, baseurl, title, view) + else: + # console mode, we just print the output + print(md) + + +def underscore_page(page): + """change spaces by underscores in the given page name""" + + if "/" in page: + page = page.split("/") + page[-1] = page[-1].replace(" ", "_") + page = "/".join(page) + else: + page.replace(" ", "_") + return page + + +def get_uri(location): + """returns a valid URI from a disk or network location""" + + baseurl = os.path.dirname(location) + "/" + if baseurl.startswith("/"): # unix path + baseurl = "file://" + baseurl + if baseurl[0].isupper() and (baseurl[1] == ":"): # windows path + baseurl = baseurl.replace("\\", "/") + baseurl = "file:///" + baseurl + return baseurl + + +def get_location(page): + """retrieves the location (online or offline) of a given page""" + + location = "" + if page.startswith("http"): + return page + if page.startswith("file://"): + return page[7:] + # offline location + if os.path.exists(page): + return page + page = page.replace(".md", "") + page = page.replace(" ", "_") + page = page.replace("wiki/", "") + page = page.split("#")[0] + suffix = PREFS.GetString("Suffix", "") + if suffix: + if not suffix.startswith("/"): + suffix = "/" + suffix + if PREFS.GetBool("optionWiki", True): # default + location = WIKI_URL + "/" + page + suffix + elif PREFS.GetBool("optionMarkdown", False): + if PREFS.GetBool("optionBrowser", False): + location = MD_RENDERED_URL + else: + location = MD_RAW_URL + if suffix: + location += "/" + MD_TRANSLATIONS_FOLDER + suffix + location += "/" + page + ".md" + elif PREFS.GetBool("optionGithub", False): + location = MD_RENDERED_URL + if suffix: + location += "/" + MD_TRANSLATIONS_FOLDER + suffix + location += "/" + page + ".md" + elif PREFS.GetBool("optionCustom", False): + location = PREFS.GetString("Location", "") + if not location: + location = os.path.join(FreeCAD.getUserAppDataDir(), "Mod", "Documentation", "wiki") + location += page + "md" + return location + + +def show_browser(url): + """opens the desktop browser with the given URL""" + + from PySide import QtCore, QtGui + + try: + ret = QtGui.QDesktopServices.openUrl(QtCore.QUrl(url)) + if not ret: + # some users reported problems with the above + import webbrowser + + webbrowser.open_new(url) + except: + import webbrowser + + webbrowser.open_new(url) + + +def show_dialog(html, baseurl, title, view=None): + """opens a dock dialog with the given html""" + + from PySide import QtCore + + if get_qtwebwidgets(html, baseurl, title): + if view: # reusing existing view + view.setHtml(html, baseUrl=QtCore.QUrl(baseurl)) + view.parent().parent().setWindowTitle(title) + else: + openBrowserHTML(html, baseurl, title, ICON, dialog=True) + + +def show_tab(html, baseurl, title, view=None): + """opens a MDI tab with the given html""" + + from PySide import QtCore + + if get_qtwebwidgets(html, baseurl, title): + if view: # reusing existing view + view.setHtml(html, baseUrl=QtCore.QUrl(baseurl)) + view.parent().parent().setWindowTitle(title) + else: + # the line below causes a crash with current Qt5 version + # openBrowserHTML(html,baseurl,title,ICON) + # so ATM we use the WebGui browser instead + import WebGui + + WebGui.openBrowserHTML(html, baseurl, title, ICON) + + +def get_qtwebwidgets(html, baseurl, title): + """opens a web module view if qtwebwidgets module is not available, and returns False""" + + try: + from PySide import QtGui, QtWebEngineWidgets + except: + FreeCAD.Console.PrintLog(LOGTXT + "\n") + import WebGui + + WebGui.openBrowserHTML(html, baseurl, title, ICON) + return False + else: + return True + + +def get_contents(location): + """retrieves text contents of a given page""" + + import urllib + + if location.startswith("http"): + import urllib.request + + try: + r = urllib.request.urlopen(location) + except: + return ERRORTXT + contents = r.read().decode("utf8") + return contents + else: + if os.path.exists(location): + with open(location, mode="r", encoding="utf8") as f: + contents = f.read() + return contents + return ERRORTXT + + +def convert(content, force=None): + """converts the given markdown code to html. Force can be None (automatic) + or markdown, pandoc, github or raw/builtin""" + + import urllib + + def convert_markdown(m): + try: + import markdown + from markdown.extensions import codehilite + + return markdown.markdown(m, extensions=["codehilite"]) + except: + return None + + def convert_pandoc(m): + try: + import pypandoc + + return pypandoc.convert_text(m, "html", format="md") + except: + return None + + def convert_github(m): + try: + import json + import urllib.request + + data = {"text": m, "mode": "markdown"} + bdata = json.dumps(data).encode("utf-8") + return ( + urllib.request.urlopen("https://api.github.com/markdown", data=bdata) + .read() + .decode("utf8") + ) + except: + return None + + def convert_raw(m): + # simple and dirty regex-based markdown to html + + import re + + f = re.DOTALL | re.MULTILINE + m = re.sub(r"^##### (.*?)\n", r"
\1
\n", m, flags=f) # ##### titles + m = re.sub(r"^#### (.*?)\n", r"

\1

\n", m, flags=f) # #### titles + m = re.sub(r"^### (.*?)\n", r"

\1

\n", m, flags=f) # ### titles + m = re.sub(r"^## (.*?)\n", r"

\1

\n", m, flags=f) # ## titles + m = re.sub(r"^# (.*?)\n", r"

\1

\n", m, flags=f) # # titles + m = re.sub(r"!\[(.*?)\]\((.*?)\)", r'\1', m, flags=f) # images + m = re.sub(r"\[(.*?)\]\((.*?)\)", r'\1', m, flags=f) # links + m = re.sub(r"\*\*(.*?)\*\*", r"\1", m) # bold + m = re.sub(r"\*(.*?)\*", r"\1", m) # italic + m = re.sub(r"\n\n", r"
", m, flags=f) # double new lines + m += "\n
" + CONVERTTXT + "" + return m + + if "\n\n\n\n\n\n' + + html + + "\n" + ) + # insert css + css = None + cssfile = PREFS.GetString("StyleSheet", "") + if not cssfile: + cssfile = os.path.join(os.path.dirname(__file__), "default.css") + if False: # linked CSS file + # below code doesn't work in FreeCAD apparently because it prohibits cross-URL stuff + cssfile = urllib.parse.urljoin("file:", urllib.request.pathname2url(cssfile)) + css = '' + else: + if os.path.exists(cssfile): + with open(cssfile) as cf: + css = cf.read() + if css: + css = "" + else: + print("Debug: Help: Unable to open css file:", cssfile) + if css: + html = html.replace("", css + "\n") + return html + + +def add_preferences_page(): + """adds the Help preferences page to the UI""" + + import FreeCADGui + + page = os.path.join(os.path.dirname(__file__), "dlgPreferencesHelp.ui") + FreeCADGui.addPreferencePage(page, QT_TRANSLATE_NOOP("QObject", "General")) + + +def add_language_path(): + """registers the Help translations to FreeCAD""" + + import FreeCADGui + import Help_rc + + FreeCADGui.addLanguagePath(":/translations") + + +def openBrowserHTML(html, baseurl, title, icon, dialog=False): + """creates a browser view and adds it as a FreeCAD MDI tab or dockable dialog""" + + import FreeCADGui + from PySide import QtCore, QtGui, QtWidgets, QtWebEngineWidgets + + # turn an int into a qt dock area + def getDockArea(area): + if area == 1: + return QtCore.Qt.LeftDockWidgetArea + elif area == 4: + return QtCore.Qt.TopDockWidgetArea + elif area == 8: + return QtCore.Qt.BottomDockWidgetArea + else: + return QtCore.Qt.RightDockWidgetArea + + # save dock widget size and location + def onDockLocationChanged(area): + PREFS.SetInt("dockWidgetArea", int(area)) + mw = FreeCADGui.getMainWindow() + dock = mw.findChild(QtWidgets.QDockWidget, "HelpWidget") + if dock: + PREFS.SetBool("dockWidgetFloat", dock.isFloating()) + PREFS.SetInt("dockWidgetWidth", dock.width()) + PREFS.SetInt("dockWidgetHeight", dock.height()) + + # a custom page that handles .md links + class HelpPage(QtWebEngineWidgets.QWebEnginePage): + def acceptNavigationRequest(self, url, _type, isMainFrame): + if _type == QtWebEngineWidgets.QWebEnginePage.NavigationTypeLinkClicked: + show(url.toString(), view=self) + return super().acceptNavigationRequest(url, _type, isMainFrame) + + mw = FreeCADGui.getMainWindow() + view = QtWebEngineWidgets.QWebEngineView() + page = HelpPage(None, view) + page.setHtml(html, baseUrl=QtCore.QUrl(baseurl)) + view.setPage(page) + + if dialog: + area = PREFS.GetInt("dockWidgetArea", 2) + floating = PREFS.GetBool("dockWidgetFloat", True) + height = PREFS.GetBool("dockWidgetWidth", 200) + width = PREFS.GetBool("dockWidgetHeight", 300) + dock = mw.findChild(QtWidgets.QDockWidget, "HelpWidget") + if not dock: + dock = QtWidgets.QDockWidget() + dock.setObjectName("HelpWidget") + mw.addDockWidget(getDockArea(area), dock) + dock.setFloating(floating) + dock.setGeometry(dock.x(), dock.y(), width, height) + dock.dockLocationChanged.connect(onDockLocationChanged) + dock.setWidget(view) + dock.setWindowTitle(title) + dock.setWindowIcon(QtGui.QIcon(icon)) + dock.show() + else: + mdi = mw.findChild(QtWidgets.QMdiArea) + sw = mdi.addSubWindow(view) + sw.setWindowTitle(title) + sw.setWindowIcon(QtGui.QIcon(icon)) + sw.show() + mdi.setActiveSubWindow(sw) diff --git a/src/Mod/Help/InitGui.py b/src/Mod/Help/InitGui.py new file mode 100644 index 000000000000..14faeedb3418 --- /dev/null +++ b/src/Mod/Help/InitGui.py @@ -0,0 +1,27 @@ +# -*- coding: utf-8 -*- + +# *************************************************************************** +# * Copyright (c) 2021 Yorik van Havre * +# * * +# * This program is free software; you can redistribute it and/or modify * +# * it under the terms of the GNU Lesser General Public License (LGPL) * +# * as published by the Free Software Foundation; either version 2 of * +# * the License, or (at your option) any later version. * +# * for detail see the LICENCE text file. * +# * * +# * This program is distributed in the hope that it will be useful, * +# * but WITHOUT ANY WARRANTY; without even the implied warranty of * +# * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * +# * GNU Library General Public License for more details. * +# * * +# * You should have received a copy of the GNU Library General Public * +# * License along with this program; if not, write to the Free Software * +# * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * +# * USA * +# * * +# *************************************************************************** + +import Help + +Help.add_preferences_page() +Help.add_language_path() diff --git a/src/Mod/Help/Resources/Help.qrc b/src/Mod/Help/Resources/Help.qrc new file mode 100644 index 000000000000..b04f86e187ce --- /dev/null +++ b/src/Mod/Help/Resources/Help.qrc @@ -0,0 +1,5 @@ + + + translations/Help_en.qm + + diff --git a/src/Mod/Help/Resources/translations/Help.ts b/src/Mod/Help/Resources/translations/Help.ts new file mode 100644 index 000000000000..241b20e742f1 --- /dev/null +++ b/src/Mod/Help/Resources/translations/Help.ts @@ -0,0 +1,210 @@ + + + + + Form + + + Help + + + + + Source + + + + + This will fetch the documentation from pages rendered on github. This is currently not available... + + + + + Github (online) + + + + + + Set this to a custom URL or the folder where the help files are located. You can easily download the documentation for offline use by using the Addon Manager and installing the "offline documentation" addon. If this field is left blank, FreeCAD will automatically search for the help files at the default location ($USERAPPDATADIR/Mod/Documentation). + + + + + Custom location + + + + + A translation suffix to use, for example "fr" to get French translation of the documentation. + + + + + Translation suffix: + + + + + The documentation pages will be fetched from the official FreeCADwiki at https://wiki.freecad.org + + + + + FreeCAD Wiki (online) + + + + + The documentation pages will be fetched from an automatic markdown conversion of the FreeCAD wiki, hosted on FreeCAD's github account. This can be styled with a custom stylesheet below and can look nicer than the wiki option. The 'markdown' or 'pandoc' python module should be installed for optimal results. + + + + + Markdown version (online) + + + + + Display + + + + + The documentation will open in a new tab inside the FreeCAD interface. + + + + + In a FreeCAD tab + + + + + The documentation will open in your default desktop browser. + + + + + In your default web browser + + + + + The documentation will open in a dockable dialog inside the FreeCAD window, which allows you to keep it open whlle working in the 3D view. + + + + + In a separate, embeddable dialog + + + + + Options + + + + + Custom stylesheet: + + + + + You can here indicate the path to an alternative CSS file to be used to style the markdown pages. This will only work if you have selected the Markdown version above. + + + + + Help + + + Contents for this page could not be retrieved. Please check settings under menu Edit -> Preferences -> General -> Help + + + + + Help files location could not be determined. Please check settings under menu Edit -> Preferences -> General -> Help + + + + + PySide2 QtWebEngineWidgets module is not available. Help rendering is done with the Web module + + + + + There is no markdown renderer installed on your system, so this help page is rendered as is. Please install the markdown or pandoc python modules to improve the rendering of this page. + + + + + + Help + + + + + Home + + + + + Forum + + + + + Wiki + + + + + Issues + + + + + Code repository + + + + + Auto Python modules + + + + + About FreeCAD + + + + + What's this? + + + + + On the web + + + + + Documentation + + + + + Shows the index page of the FreeCAD documentation + + + + + QObject + + + General + + + + diff --git a/src/Mod/Help/Resources/translations/Help_en.qm b/src/Mod/Help/Resources/translations/Help_en.qm new file mode 100644 index 000000000000..be651eede2ed --- /dev/null +++ b/src/Mod/Help/Resources/translations/Help_en.qm @@ -0,0 +1 @@ +<¸dÊÍ!¿`¡½Ý \ No newline at end of file diff --git a/src/Mod/Help/Resources/translations/Help_en.ts b/src/Mod/Help/Resources/translations/Help_en.ts new file mode 100644 index 000000000000..241b20e742f1 --- /dev/null +++ b/src/Mod/Help/Resources/translations/Help_en.ts @@ -0,0 +1,210 @@ + + + + + Form + + + Help + + + + + Source + + + + + This will fetch the documentation from pages rendered on github. This is currently not available... + + + + + Github (online) + + + + + + Set this to a custom URL or the folder where the help files are located. You can easily download the documentation for offline use by using the Addon Manager and installing the "offline documentation" addon. If this field is left blank, FreeCAD will automatically search for the help files at the default location ($USERAPPDATADIR/Mod/Documentation). + + + + + Custom location + + + + + A translation suffix to use, for example "fr" to get French translation of the documentation. + + + + + Translation suffix: + + + + + The documentation pages will be fetched from the official FreeCADwiki at https://wiki.freecad.org + + + + + FreeCAD Wiki (online) + + + + + The documentation pages will be fetched from an automatic markdown conversion of the FreeCAD wiki, hosted on FreeCAD's github account. This can be styled with a custom stylesheet below and can look nicer than the wiki option. The 'markdown' or 'pandoc' python module should be installed for optimal results. + + + + + Markdown version (online) + + + + + Display + + + + + The documentation will open in a new tab inside the FreeCAD interface. + + + + + In a FreeCAD tab + + + + + The documentation will open in your default desktop browser. + + + + + In your default web browser + + + + + The documentation will open in a dockable dialog inside the FreeCAD window, which allows you to keep it open whlle working in the 3D view. + + + + + In a separate, embeddable dialog + + + + + Options + + + + + Custom stylesheet: + + + + + You can here indicate the path to an alternative CSS file to be used to style the markdown pages. This will only work if you have selected the Markdown version above. + + + + + Help + + + Contents for this page could not be retrieved. Please check settings under menu Edit -> Preferences -> General -> Help + + + + + Help files location could not be determined. Please check settings under menu Edit -> Preferences -> General -> Help + + + + + PySide2 QtWebEngineWidgets module is not available. Help rendering is done with the Web module + + + + + There is no markdown renderer installed on your system, so this help page is rendered as is. Please install the markdown or pandoc python modules to improve the rendering of this page. + + + + + + Help + + + + + Home + + + + + Forum + + + + + Wiki + + + + + Issues + + + + + Code repository + + + + + Auto Python modules + + + + + About FreeCAD + + + + + What's this? + + + + + On the web + + + + + Documentation + + + + + Shows the index page of the FreeCAD documentation + + + + + QObject + + + General + + + + diff --git a/src/Mod/Help/default.css b/src/Mod/Help/default.css new file mode 100644 index 000000000000..dd281cbf640b --- /dev/null +++ b/src/Mod/Help/default.css @@ -0,0 +1,19 @@ +/* our own FreeCAD styling */ + +html { color: #000000; font-family: "sans"; background: #ffffff; } +a { color: #3071B1; font-weight: bold; } +body { max-width: 800px; text-align: justify; margin:10px auto; padding: 10px; } +img { max-width: 100%; margin: 10px 0; } +li { padding: 5px 0; } +li img { vertical-align:middle; margin: 0; } +pre, code { background: #eeeeee; white-space: pre-wrap; } +pre { padding: 10px; } +code { padding: 2px 5px; } +h1, h2, h3, h4, h5 { margin: 25px 0; color: #222222; } +h1 { border-bottom: 1px solid #000000; } + +/* codehilite */ + +.dv { color: #9A0000; } /* numbers */ +.im { color: #0A1F96; font-weight: bold; } /* import */ +.op { color: #333333; } /* operators */ diff --git a/src/Mod/Help/dlgPreferencesHelp.ui b/src/Mod/Help/dlgPreferencesHelp.ui new file mode 100644 index 000000000000..dd19ccbf6e5e --- /dev/null +++ b/src/Mod/Help/dlgPreferencesHelp.ui @@ -0,0 +1,279 @@ + + + Form + + + + 0 + 0 + 504 + 549 + + + + Help + + + + + + Source + + + + + + false + + + This will fetch the documentation from pages rendered on github. This is currently not available... + + + Github (online) + + + optionGithub + + + Mod/Help + + + + + + + Set this to a custom URL or the folder where the help files are located. You can easily download the documentation for offline use by using the Addon Manager and installing the "offline documentation" addon. If this field is left blank, FreeCAD will automatically search for the help files at the default location ($USERAPPDATADIR/Mod/Documentation). + + + Custom location + + + optionCustom + + + Mod/Help + + + + + + + + 100 + 16777215 + + + + A translation suffix to use, for example "fr" to get French translation of the documentation. + + + Suffix + + + Mod/Help + + + + + + + Set this to a custom URL or the folder where the help files are located. You can easily download the documentation for offline use by using the Addon Manager and installing the "offline documentation" addon. If this field is left blank, FreeCAD will automatically search for the help files at the default location ($USERAPPDATADIR/Mod/Documentation). + + + + + + Location + + + Mod/Help + + + + + + + Qt::LeftToRight + + + Translation suffix: + + + + + + + The documentation pages will be fetched from the official FreeCADwiki at https://wiki.freecad.org + + + FreeCAD Wiki (online) + + + true + + + optionWiki + + + Mod/Help + + + + + + + The documentation pages will be fetched from an automatic markdown conversion of the FreeCAD wiki, hosted on FreeCAD's github account. This can be styled with a custom stylesheet below and can look nicer than the wiki option. The 'markdown' or 'pandoc' python module should be installed for optimal results. + + + Markdown version (online) + + + false + + + optionMarkdown + + + Mod/Help + + + + + + + + + + Display + + + + + + The documentation will open in a new tab inside the FreeCAD interface. + + + In a FreeCAD tab + + + true + + + optionTab + + + Mod/Help + + + + + + + The documentation will open in your default desktop browser. + + + In your default web browser + + + optionBrowser + + + Mod/Help + + + + + + + true + + + The documentation will open in a dockable dialog inside the FreeCAD window, which allows you to keep it open whlle working in the 3D view. + + + In a separate, embeddable dialog + + + optionDialog + + + Mod/Help + + + + + + + + + + Options + + + + + + + + Custom stylesheet: + + + + + + + You can here indicate the path to an alternative CSS file to be used to style the markdown pages. This will only work if you have selected the Markdown version above. + + + StyleSheet + + + Mod/Help + + + + + + + + + + + + Qt::Vertical + + + + 20 + 40 + + + + + + + + + Gui::FileChooser + QWidget +
Gui/FileDialog.h
+ + + Gui::PrefFileChooser + Gui::FileChooser +
Gui/PrefWidgets.h
+ + + Gui::PrefRadioButton + QRadioButton +
Gui/PrefWidgets.h
+ + + Gui::PrefLineEdit + QLineEdit +
Gui/PrefWidgets.h
+ + + + + diff --git a/src/Tools/updatecrowdin.py b/src/Tools/updatecrowdin.py index d50160cf975a..57c17d890f3a 100755 --- a/src/Tools/updatecrowdin.py +++ b/src/Tools/updatecrowdin.py @@ -99,6 +99,7 @@ "Material", "OpenSCAD", "Tux", + "Help", } # locations list contains Module name, relative path to translation folder and relative path to qrc file @@ -128,6 +129,7 @@ "../Mod/Fem/Gui/Resources/Fem.qrc", ], ["FreeCAD", "../Gui/Language", "../Gui/Language/translation.qrc"], + ["Help", "../Mod/Help/Resources/translations", "../Mod/Help/Resources/Help.qrc"], [ "Inspection", "../Mod/Inspection/Gui/Resources/translations", diff --git a/src/Tools/updatets.py b/src/Tools/updatets.py index 0aa18108d145..0f9b3bed1ece 100755 --- a/src/Tools/updatets.py +++ b/src/Tools/updatets.py @@ -172,6 +172,11 @@ "workingdir": "./src/Mod/Web/", "tsdir": "Gui/Resources/translations", }, + { + "tsname": "Help", + "workingdir": "./src/Mod/Help/", + "tsdir": "Resources/translations", + }, ] # Exclude these files from consideration