Merge pull request #725 from Fortran-FOSS-Programmers/better-externalise-docs

Always export `modules.json` for external projects

Author: ZedThree

docs/user_guide/project_file_options.rst

@@ -862,13 +862,28 @@ external
 
 Paths or URLs of external projects to link to. If an entity is not found in the
 sources, FORD will try to look it up in those external projects. If those have
-documentation generated by FORD with the externalize option, a link will be
-placed into the documentation wherever this entity is referred to. FORD will
-look in the provided paths for a ``modules.json`` file.
+documentation generated by FORD with the `externalize <option-externalize>`
+option, a link will be placed into the documentation wherever this entity is
+referred to. FORD will look in the provided paths for a ``modules.json`` file.
 
-The difference between ``external`` between ``extra_mods`` is that FORD can link
-directly to entities (functions, types, and so on) with ``external``, while only
-modules will be linked to using ``extra_mods``.
+The difference between ``external`` between `extra_mods <option-extra_mods>` is
+that FORD can link directly to entities (functions, types, and so on) with
+``external``, while only modules will be linked to using ``extra_mods``.
+
+.. tab:: fpm.toml
+
+   .. code:: toml
+
+      [extra.ford.external]
+      example_project = "https://docs.example.com"
+      fmin = "https://jacobwilliams.github.io/fmin/"
+
+.. tab:: Markdown metadata
+
+   .. code:: yaml
+
+      external: example_project=https://docs.example.com
+          fmin=https://jacobwilliams.github.io/fmin/
 
 .. _option-extra_mods:
 
@@ -1152,6 +1167,9 @@ Create a ``modules.json`` file under `option-output_dir` containing information
 about entities and the URL of their documentation. This allows this project to
 be used as an `option-external` link in another project.
 
+.. versionchanged:: 7.0.13
+   This option is now ``True`` by default
+
 .. _option-graph_dir:
 
 graph_dir

docs/user_guide/writing_documentation.rst

@@ -352,6 +352,42 @@ constructor.
    ``my_subroutine``, while now it will be left as: ``call
    [[my_subroutine]]``.
 
+.. _external_projects:
+
+Linking to External Projects
+----------------------------
+
+FORD can look up references to modules, routines, and types in other projects if
+they also use FORD for documentation.
+This works in two steps:
+
+- the external project exports the information about each entity, including
+  links, to a ``modules.json`` file, which is hosted along with the rest of the
+  documentation.
+
+  .. versionchanged:: 7.0.13
+     Prior to 7.0.13, the external project has to set `externalize = True
+     <option-externalize>` in order to create the ``modules.json`` file. In
+     7.0.13, this is now the default behaviour.
+
+- the downstream project imports the external project using the `external
+  <option-external>` setting, specifying the name of the project and (usually)
+  the top-level URL of the project's documentation. For example, if the front
+  page of your FORD docs is at ``project.github.io``, you would set:
+
+.. tab:: fpm.toml
+
+   .. code:: toml
+
+      [extra.ford.external]
+      name = "https://project.github.io"
+
+.. tab:: Markdown metadata
+
+   .. code:: yaml
+
+      external: name=https://project.github.io
+
 .. _non-fortran-source-files:
 
 Non-Fortran Source Files

ford/__init__.py

@@ -271,13 +271,30 @@ def get_command_line_arguments() -> argparse.Namespace:
         help="list of directories to be searched for ``include`` files",
     )
     parser.add_argument(
+        "--config",
+        type=str,
+        default=None,
+        help="Any other FORD options as a semicolon-separated TOML string. "
+        "Options set through this have lower precedence than other command line options",
+    )
+
+    external_group = parser.add_argument_group("external projects")
+    externalize_group = external_group.add_mutually_exclusive_group()
+    externalize_group.add_argument(
         "--externalize",
         action="store_true",
-        default=None,
-        help="provide information about Fortran objects in a json database for "
-        "other FORD projects to refer to.",
+        default=True,
+        help="export information about Fortran objects to JSON file for "
+        "other FORD projects to use (default: True)",
     )
-    parser.add_argument(
+    externalize_group.add_argument(
+        "--no-externalize",
+        action="store_false",
+        dest="externalize",
+        help="don't export information to JSON file",
+    )
+
+    external_group.add_argument(
         "-L",
         "--external_links",
         dest="external",
@@ -290,13 +307,6 @@ def get_command_line_arguments() -> argparse.Namespace:
         FORD will look in the provided paths for a modules.json file.
         """,
     )
-    parser.add_argument(
-        "--config",
-        type=str,
-        default=None,
-        help="Any other FORD options as a semicolon-separated TOML string. "
-        "Options set through this have lower precedence than other command line options",
-    )
 
     return parser.parse_args()
 

ford/settings.py

@@ -142,7 +142,7 @@ class ProjectSettings:
         default_factory=lambda: ["f90", "f95", "f03", "f08", "f15"]
     )
     external: Dict[str, str] = field(default_factory=dict)
-    externalize: bool = False
+    externalize: bool = True
     extra_filetypes: Dict[str, ExtraFileType] = field(default_factory=dict)
     extra_mods: Dict[str, str] = field(default_factory=dict)
     extra_vartypes: list = field(default_factory=list)