{"id":19856851,"url":"https://github.com/albar965/littlenavmap-manual","last_synced_at":"2025-10-10T18:16:22.323Z","repository":{"id":36996623,"uuid":"135903234","full_name":"albar965/littlenavmap-manual","owner":"albar965","description":"The sources for the Little Navmap user manual which is hosted on www.littlenavmap.org.","archived":false,"fork":false,"pushed_at":"2025-07-24T11:05:29.000Z","size":92185,"stargazers_count":7,"open_issues_count":2,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-29T07:49:31.093Z","etag":null,"topics":["flight","flightplan","flightplanner","fsx","map","navigation","prepar3d","simulator","x-plane"],"latest_commit_sha":null,"homepage":"https://albar965.github.io/manuals.html","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/albar965.png","metadata":{"files":{"readme":"README-Sphinx.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-06-03T12:43:39.000Z","updated_at":"2025-07-24T11:05:34.000Z","dependencies_parsed_at":"2025-07-24T13:23:57.412Z","dependency_job_id":null,"html_url":"https://github.com/albar965/littlenavmap-manual","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/albar965/littlenavmap-manual","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albar965%2Flittlenavmap-manual","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albar965%2Flittlenavmap-manual/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albar965%2Flittlenavmap-manual/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albar965%2Flittlenavmap-manual/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/albar965","download_url":"https://codeload.github.com/albar965/littlenavmap-manual/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albar965%2Flittlenavmap-manual/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004913,"owners_count":26083802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flight","flightplan","flightplanner","fsx","map","navigation","prepar3d","simulator","x-plane"],"created_at":"2024-11-12T14:16:45.219Z","updated_at":"2025-10-10T18:16:22.307Z","avatar_url":"https://github.com/albar965.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Document Format Change\n==========================\n\nSphinx is the future documentation generation tool for *Little Navmap*. A change was needed\ndue to to regressions (e.g. dropping of PDF, format closed now and more) of\nGitbook (`#238 \u003chttps://github.com/albar965/littlenavmap/issues/238\u003e`_) which make it unusable.\n\nThis means a change from the Markdown format to the similar reStructuredText (reST) as well as a\nchange of the whole toolchain.\n\nThe old Markdown files can be converted to reStructuredText using `Pandoc \u003chttps://pandoc.org/\u003e`_.\nThe results still have to be adapted manually, though.\n\nThe manual adaption is already completely finished for the English and German part of the manual\nwhich can be used as templates for other languages.\n\nThe new documentation style will rollout with *Little Navmap* 2.6.\n\nBTW: This is a reStructuredText document.\n\nIssues can be submitted at https://github.com/albar965/littlenavmap/issues .\n\nExamples\n----------\n\nThe Sphinx generated English documentation for *Little Navmap* can be accessed here:\n\n* `HTML \u003chttps://www.littlenavmap.org/manuals/littlenavmap/develop/2.6/en/\u003e`_\n* `PDF A4 \u003chttps://www.littlenavmap.org/manuals/littlenavmap/develop/2.6/littlenavmap_book_en_a4.pdf\u003e`_\n* `PDF US Letter \u003chttps://www.littlenavmap.org/manuals/littlenavmap/develop/2.6/littlenavmap_book_en_letter.pdf\u003e`_\n* `ePUB \u003chttps://www.littlenavmap.org/manuals/littlenavmap/develop/2.6/littlenavmap_book_en.epub\u003e`_\n* `MOBI \u003chttps://www.littlenavmap.org/manuals/littlenavmap/develop/2.6/littlenavmap_book_en.mobi\u003e`_\n\nWhy Sphinx?\n-----------\n\n#. It is an open document generator which can be run on Linux, Windows and macOS to\n   create the documentation.\n#. Documents contain an index for all headlines.\n#. Does error checking on internal and external links.\n#. reStructuredText provides more formatting features than Markdown.\n#. Better search with highlighting of terms in page.\n#. Much faster compilation than the now unsupported Gitbook toolchain.\n#. Generated documents work correctly with anchors. Gitbook generated documentation\n   often missed anchors in the middle of a page when loading them due to the\n   useless smooth scroll feature.\n#. Supports anchors which are needed for internal cross references and help buttons\n   in *Little Navmap*.\n#. Can generate ePUB format which can be converted to PDF and MOBI including working\n   links and index.\n\nTools\n----------\n\nThe following tools are needed to compile the HTML and ePUB documentation:\n\n* `Sphinx installation \u003chttps://www.sphinx-doc.org/en/master/usage/installation.html\u003e`_\n* `Read the Docs Sphinx Theme \u003chttps://pypi.org/project/sphinx-rtd-theme/\u003e`_ and\n  `Installation \u003chttps://sphinx-rtd-theme.readthedocs.io/en/stable/\u003e`_.\n\n`Calibre \u003chttps://calibre-ebook.com/download\u003e`_ command line tools are only needed\nto convert ePUB to MOBI and PDF.\n\nUseful Links\n---------------\n\n* `Sphinx Documentation Generator \u003chttps://www.sphinx-doc.org/\u003e`_\n* `Quick reference for reStructuredText \u003chttp://docutils.sourceforge.net/docs/user/rst/quickref.html\u003e`_\n* `reStructuredText Primer \u003chttps://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html\u003e`_\n* `Calibre e-book manager and tools \u003chttps://calibre-ebook.com/\u003e`_\n* `Pandoc universal document converter \u003chttps://pandoc.org/\u003e`_\n* `Try pandoc. Convert Markdown to reStructuredText on the fly \u003chttps://pandoc.org/try/\u003e`_\n* `Online reStructuredText editor. Write reST and see the results immediately \u003chttp://rst.ninjs.org/\u003e`_\n\nBuild and conversion Scripts\n---------------------------------\n\n* ``sphinx_convert.sh``: Converts all Markdown scripts to reST and stores the files\n  in ``src/XX`` where ``XX`` is the used language code. Takes a list of language codes as a\n  parameter. **Do not run this for the English and German branches which are already finished.**\n* ``sphinx_build.sh``: Compiles only the changed ``.rst``-files.\n  Takes the target format (``html`` or ``epub``) as the first and a list of language codes as\n  following parameters. The results are stored in the directory ``build``.\n  Run ``sphinx_build.sh html en de`` to generate  the English and German HTML documents, for example.\n* ``sphinx_rebuild.sh``: Same as ``sphinx_build.sh`` but also compiles unchanged files.\n* ``sphinx_rebuild_all.sh``: Compiles the HTML and ePUB documentation and converts\n  ePUB to PDF and MOBI. Takes a list of language codes as a parameter. All results are stored in\n  the directory ``deploy``. Needs Calibre command line tools.\n\nDirectories\n---------------------------------\n\nAll except the listed folders here belong to the old Gitbook Markown documentation and will be\nremoved in future versions.\n\n* ``src``: Source folder with a subfolder for each language containing the\n  reST (``*.rst``) documents. All documents can be converted to the reST format using Pandoc.\n  Populated using the ``sphinx_convert.sh`` script.\n* ``build``: Folder for intermediate results when building the HTML and ePUB formats.\n  You can find the English HTML documentation here: ``build/html/en/index.html`` after\n  building, for example.\n* ``src/conf.py``: `Sphinx configuration file \u003chttps://www.sphinx-doc.org/en/master/usage/configuration.html\u003e`_.\n* ``src/XX/index.rst``: Top level index file for language code ``XX``.\n\nFiles created by running the script ``sphinx_rebuild_all.sh en``:\n\n* ``deploy/en``: HTML documentation with all unneccesary files stripped off.\n* ``deploy/littlenavmap_book_en.epub``: ePUB ebook format.\n* ``deploy/littlenavmap_book_en.mobi``: MOBI ebook format.\n* ``deploy/littlenavmap_book_en_a4.pdf``: PDF using A4 page size.\n* ``deploy/littlenavmap_book_en_letter.pdf``: PDF using US letter format.\n\nHow adjust the Pandoc converted files\n-----------------------------------------------\n\nConverted files need manual adjustments which I cannot do for all languages.\nNote that some adaptions are optional.\n\nPlease install the Sphinx tools locally to test your translation. Using the tools\ngives you clear error messages when compiling the manual. You can also use the online\ntools linked above for quick tests.\n\nNote that reST is dependent on indention with spaces for certain directives. You have to use\nfour or more spaces to define blocks.\n\nTables\n~~~~~~~~~~~~~~\n\nTables are not converted properly. Copy the tables from the English reST files and insert your\ntranslated texts there. I recommend to use simple tables as described in\n`Tables \u003chttps://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables\u003e`__.\n\nNote that Sphinx is very picky about alignment in tables.\n\nCode blocks\n~~~~~~~~~~~~~~\n\nCode blocks can be copied from the English manual as is. These don't need a translation.\nThe blocks can be found by looking for the ``.. code-block::`` directive in the\nEnglish reST files.\n\nLists\n~~~~~~~~~~~~~~\n\nNested lists are not converted properly by Pandoc. You have to add an empty line before and after a\nnested list and indent it.\n\nExample for a corrected sub list::\n\n   - List item 1\n   - List item 2\n\n       - Sub item 1\n       - Sub item 2\n\n   - List item 3\n\nIn some cases lists are collapsed to a single line. You can find these by looking for an\nescaped star (``\\*``).\n\nImages\n~~~~~~~~~~~~~~\n\nSmall inline images like toolbar icons can be left as they are converted by Pandoc.\n\nImages with a caption can be converted, though.\n\nLook for the text ``Image Above`` (the translated phrase) in your converted reST file\nand replace it with a figure directive (``.. figure::``).\n\nImage references are enclosed in ``|`` and refer to an image at the bottom of the file.\nYou have to inline these.\n\nExample source image before conversion::\n\n      |Little Navmap Overview|\n\n      **Image ci-dessus:**\\ *Un bref aperçu de Little Navmap v1.8.5 montrant\n      les fonctions les plus importantes.*\n\n      ... more text until bottom of file\n\n      .. |Little Navmap Overview| image:: ../images/overview.jpg\n\nAfter conversion::\n\n   .. figure:: ../images/overview.jpg\n\n        Un bref aperçu de Little Navmap v1.8.5 montrant\n        les fonctions les plus importantes.\n\nNote that the ``Image ci-dessus:`` (``Image above``) can be removed and bold or italic is not needed anymore.\n\nSee also\n`Images \u003chttps://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#images\u003e`__ and\n`Figures \u003chttp://docutils.sourceforge.net/docs/ref/rst/directives.html#figure\u003e`__.\n\nNested bold, italic and/or code styles\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nNesting text styles like italic and bold is not allowed in reST. Pandoc escapes styles with an\nbackslash ``\\`` which can be removed.\n\nExample markdown with nested styles::\n\n   **Bold text with *italic* text mixed.**\n\n   *Italic text mixed with `code`.*\n\nExample reST cleaned up::\n\n    **Bold text with** *italic* **text mixed.**\n\n    *Italic text mixed with* ``code`` *.*\n\nNote the space before ``*.*``. Do **not** add a space before ``Italic`` and after ``with``.\nTry the online tools if in doubt about the outcome.\n\nReferences\n~~~~~~~~~~~~~~\n\nPandoc creates external references per default. These can (optionally) be converted to internal\nreferences using HTML anchors.\n\nExample in Pandoc reST converted text::\n\n    `Tableau des résultats de recherche - Afficher le Menu Contextuel \u003cSEARCH.html#search-result-table-view-context-menu\u003e`__\n\nExternal link replaced with an anchor::\n\n    :ref:`search-result-table-view-context-menu`\n\nYou can also use the ``:doc:`` directive to refer to documents::\n\n    :doc:`SEARCH`\n\nSphinx will use the text from the next header after an anchor or at the top of a file as link text.\n\nSee also\n`Cross-referencing arbitrary locations \u003chttps://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-arbitrary-locations\u003e`__ and\n`Cross-referencing documents \u003chttps://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-documents\u003e`__.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbar965%2Flittlenavmap-manual","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falbar965%2Flittlenavmap-manual","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbar965%2Flittlenavmap-manual/lists"}