Merge pull request #697 from Fortran-FOSS-Programmers/fix-docs-fpm-toml

Fix some issues with using `fpm.toml`

Author: ZedThree

docs/user_guide/project_file_options.rst

@@ -11,6 +11,14 @@ ways:
 2. in the ``extra.ford`` table of your `fpm.toml
    <https://fpm.fortran-lang.org>`_ file (*new in version 7.0*).
 
+We recommend using ``fpm.toml`` for Ford settings as it allows comments and the
+syntax is a bit more forgiving. Ford is still run the same way in either case:
+
+.. code:: console
+
+   $ ford <project-file.md>
+
+
 .. _sec-fpm-toml:
 
 ``fpm.toml`` File

example/example-project-file.md

@@ -1,37 +1,3 @@
----
-project: Example Project
-summary: This is a short example project
-    that demonstrates many of Ford's features
-src_dir: ./src
-output_dir: ./doc
-project_github: https://github.com/cmacmackin/futility
-project_website: https://github.com
-summary: Some Fortran program which I wrote.
-author: John Doe
-author_description: I program stuff in Fortran.
-github: https://github.com/cmacmackin
-email: [email protected]
-fpp_extensions: fpp
-preprocess: true
-macro: HAS_DECREMENT
-predocmark: >
-docmark_alt: #
-predocmark_alt: <
-display: public
-         protected
-source: false
-graph: true
-search: true
-extra_mods: json_module: http://jacobwilliams.github.io/json-fortran/
-            futility: http://cmacmackin.github.io
-license: by-nc
-extra_filetypes: sh #
-max_frontpage_items: 4
-exclude: src/excluded_file.f90
-exclude_dir: src/excluded_directory
-page_dir: pages
----
-
 Hi, my name is ${USER}.
 
 This is a project which I wrote. This file will provide the documents. I'm

example/fpm.toml

@@ -0,0 +1,32 @@
+[extra.ford]
+project = "Example Project"
+src_dir = "./src"
+output_dir = "./doc"
+project_github = "https://github.com/cmacmackin/futility"
+project_website = "https://github.com"
+summary = "Some Fortran program which I wrote."
+author = "John Doe"
+author_description = "I program stuff in Fortran."
+github = "https://github.com/cmacmackin"
+email = "[email protected]"
+fpp_extensions = ["fpp"]
+preprocess = "true"
+macro = ["HAS_DECREMENT"]
+predocmark = ">"
+docmark_alt = "#"
+predocmark_alt = "<"
+display = ["public", "protected"]
+source = false
+graph = true
+search = true
+license = "by-nc"
+extra_filetypes = [{extension = "sh", comment="#"}]
+max_frontpage_items = "4"
+exclude = "src/excluded_file.f90"
+exclude_dir = "src/excluded_directory"
+page_dir = "pages"
+
+[extra.ford.extra_mods]
+json_module = "http://jacobwilliams.github.io/json-fortran/"
+futility = "http://cmacmackin.github.io"
+iso_fortran_env = "https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html"

ford/settings.py

@@ -147,10 +147,12 @@ class ProjectSettings:
     extra_vartypes: list = field(default_factory=list)
     facebook: Optional[str] = None
     favicon: Path = FAVICON_PATH
-    fixed_extensions: list = field(default_factory=lambda: ["f", "for", "F", "FOR"])
+    fixed_extensions: List[str] = field(
+        default_factory=lambda: ["f", "for", "F", "FOR"]
+    )
     fixed_length_limit: bool = True
     force: bool = False
-    fpp_extensions: list = field(
+    fpp_extensions: List[str] = field(
         default_factory=lambda: ["F90", "F95", "F03", "F08", "F15", "F", "FOR"]
     )
     github: Optional[str] = None
@@ -168,11 +170,11 @@ class ProjectSettings:
     license: str = ""
     linkedin: Optional[str] = None
     lower: bool = False
-    macro: list = field(default_factory=list)
+    macro: List[str] = field(default_factory=list)
     mathjax_config: Optional[Path] = None
     max_frontpage_items: int = 10
     md_base_dir: Path = Path(".")
-    md_extensions: list = field(default_factory=list)
+    md_extensions: List[str] = field(default_factory=list)
     media_dir: Optional[Path] = None
     output_dir: Path = Path("./doc")
     page_dir: Optional[Path] = None

test/conftest.py

@@ -3,6 +3,8 @@
 import pytest
 from textwrap import dedent
 import subprocess
+from contextlib import contextmanager
+import os
 
 # Ford default src folder
 DEFAULT_SRC = "src"
@@ -39,3 +41,11 @@ def gfortran_is_not_installed():
     """Returns False if gfortran is not (detectably) installed"""
     out = subprocess.run("command -v gfortran", shell=True, check=False)
     return out.returncode != 0
+
+
+@contextmanager
+def chdir(directory):
+    oldwd = os.getcwd()
+    os.chdir(directory)
+    yield
+    os.chdir(oldwd)

test/test_example.py

@@ -1,6 +1,5 @@
 import shutil
 import sys
-import os
 import pathlib
 import re
 from urllib.parse import urlparse
@@ -11,6 +10,8 @@
 from bs4 import BeautifulSoup
 import pytest
 
+from conftest import chdir
+
 
 pytestmark = pytest.mark.filterwarnings("ignore::bs4.MarkupResemblesLocatorWarning")
 
@@ -29,15 +30,14 @@ def example_project(tmp_path_factory):
     tmp_path = tmp_path_factory.getbasetemp() / "example"
     shutil.copytree(this_dir / "../example", tmp_path)
 
-    with pytest.MonkeyPatch.context() as m:
-        os.chdir(tmp_path)
+    with pytest.MonkeyPatch.context() as m, chdir(tmp_path):
         m.setattr(sys, "argv", ["ford", "example-project-file.md"])
         ford.run()
 
     with open(tmp_path / "example-project-file.md", "r") as f:
         project_file = f.read()
 
-    project_file, project_settings = ford.load_settings(project_file)
+    project_file, project_settings = ford.load_settings(project_file, tmp_path)
     settings, _ = ford.parse_arguments({}, project_file, project_settings, tmp_path)
 
     doc_path = tmp_path / "doc"

test/test_initialisation.py

@@ -13,10 +13,10 @@ class FakeFile:
     name = "test file"
 
 
-def test_quiet_false():
-    _, data = ford.load_settings("quiet: False")
+def test_quiet_false(tmp_path):
+    _, data = ford.load_settings("quiet: False", tmp_path)
     assert data.quiet is False
-    _, data2 = ford.load_settings("quiet: True")
+    _, data2 = ford.load_settings("quiet: True", tmp_path)
     assert data2.quiet is True
 
 
@@ -54,7 +54,7 @@ def test_quiet_command_line():
     assert data.quiet is False
 
 
-def test_list_input():
+def test_list_input(tmp_path):
     """Check that setting a non-list option is turned into a single string"""
 
     settings = """\
@@ -65,7 +65,7 @@ def test_list_input():
              one
              string
     """
-    _, data = ford.load_settings(dedent(settings))
+    _, data = ford.load_settings(dedent(settings), tmp_path)
 
     assert len(data.include) == 2
     assert data.summary == "This\nis\none\nstring"

test/test_projects/test_external_project.py

@@ -11,6 +11,7 @@
 from bs4 import BeautifulSoup
 import pytest
 
+from conftest import chdir
 
 REMOTE_TYPE_JSON: Dict[str, Any] = {
     "name": "remote_type",
@@ -109,17 +110,15 @@ def external_project(tmp_path_factory, monkeymodule):
 
     # Run FORD in the two projects
     # First project has "externalize: True" and will generate JSON dump
-    with monkeymodule.context() as m:
-        os.chdir(external_project)
+    with monkeymodule.context() as m, chdir(external_project):
         m.setattr(sys, "argv", ["ford", "doc.md"])
         ford.run()
 
     def mock_open(*args, **kwargs):
         return MockResponse()
 
     # Second project uses JSON from first to link to external modules
-    with monkeymodule.context() as m:
-        os.chdir(top_level_project)
+    with monkeymodule.context() as m, chdir(top_level_project):
         m.setattr(sys, "argv", ["ford", "doc.md"])
         m.setattr(ford.external_project, "urlopen", mock_open)
         ford.run()