Repository: mkdocs/mkdocs

Issue:
Deprecated --theme-dir is still listed as CLI option
Hey, I am busy migrating my project from v0.16.3 to v1.1 and it seems that the command line argument `-e / --theme-dir PATH` has been removed, I am defining a custom theme using the theme block and the `custom_dir` but the way we have things setup require us to use use the `--theme-dir` config as well, I don't suppose there is a replacement for that argument is there?

Thanks!


Discussion:
No, not directly. `theme_dir` was replaced by `theme.name` where name is an entry_point which points to an installed theme. Therefore, you would need to make the content of `theme_dir` its own Python package/theme, install it, and then set `theme.name` to the name of that theme. This is documented under [Packaging Themes][1] in the documentation.

[1]: https://www.mkdocs.org/user-guide/custom-themes/#packaging-themes
Thanks, I was able to solve my problem, but the information out there is still rather confusing,
`mkdocs build -h` lists `-e --theme-dir` as an option still, but then says it doesn't recognise it, can get a bit confusing.
> `mkdocs build -h` lists `-e --theme-dir` as an option still

That is a bug. That option should be removed.

Resolving patch:
diff --git a/mkdocs/__main__.py b/mkdocs/__main__.py
--- a/mkdocs/__main__.py
+++ b/mkdocs/__main__.py
@@ -41,7 +41,6 @@ def __init__(self, log_name='mkdocs', level=logging.INFO):
                  "localhost:8000)")
 strict_help = ("Enable strict mode. This will cause MkDocs to abort the build "
                "on any warnings.")
-theme_dir_help = "The theme directory to use when building your documentation."
 theme_help = "The theme to use when building your documentation."
 theme_choices = utils.get_theme_names()
 site_dir_help = "The directory to output the result of the documentation build."
@@ -99,7 +98,6 @@ def callback(ctx, param, value):
     # Conveniently, load_config drops None values
     click.option('-s', '--strict', is_flag=True, default=None, help=strict_help),
     click.option('-t', '--theme', type=click.Choice(theme_choices), help=theme_help),
-    click.option('-e', '--theme-dir', type=click.Path(), help=theme_dir_help),
     # As with --strict, set the default to None so that this doesn't incorrectly
     # override the config file
     click.option('--use-directory-urls/--no-directory-urls', is_flag=True, default=None, help=use_directory_urls_help)


Test patch:
diff --git a/mkdocs/tests/cli_tests.py b/mkdocs/tests/cli_tests.py
--- a/mkdocs/tests/cli_tests.py
+++ b/mkdocs/tests/cli_tests.py
@@ -28,7 +28,6 @@ def test_serve_default(self, mock_serve):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None
         )
 
@@ -58,7 +57,6 @@ def test_serve_dev_addr(self, mock_serve):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None
         )
 
@@ -75,7 +73,6 @@ def test_serve_strict(self, mock_serve):
             config_file=None,
             strict=True,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None
         )
 
@@ -92,24 +89,6 @@ def test_serve_theme(self, mock_serve):
             config_file=None,
             strict=None,
             theme='readthedocs',
-            theme_dir=None,
-            use_directory_urls=None
-        )
-
-    @mock.patch('mkdocs.commands.serve.serve', autospec=True)
-    def test_serve_theme_dir(self, mock_serve):
-
-        result = self.runner.invoke(
-            cli.cli, ["serve", '--theme-dir', 'custom'], catch_exceptions=False)
-
-        self.assertEqual(result.exit_code, 0)
-        mock_serve.assert_called_once_with(
-            dev_addr=None,
-            livereload='livereload',
-            config_file=None,
-            strict=None,
-            theme=None,
-            theme_dir='custom',
             use_directory_urls=None
         )
 
@@ -126,7 +105,6 @@ def test_serve_use_directory_urls(self, mock_serve):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=True
         )
 
@@ -143,7 +121,6 @@ def test_serve_no_directory_urls(self, mock_serve):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=False
         )
 
@@ -160,7 +137,6 @@ def test_serve_livereload(self, mock_serve):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None
         )
 
@@ -177,7 +153,6 @@ def test_serve_no_livereload(self, mock_serve):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None
         )
 
@@ -194,7 +169,6 @@ def test_serve_dirtyreload(self, mock_serve):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None
         )
 
@@ -214,7 +188,6 @@ def test_build_defaults(self, mock_build, mock_load_config):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None,
             site_dir=None
         )
@@ -275,7 +248,6 @@ def test_build_strict(self, mock_build, mock_load_config):
             config_file=None,
             strict=True,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None,
             site_dir=None
         )
@@ -293,25 +265,6 @@ def test_build_theme(self, mock_build, mock_load_config):
             config_file=None,
             strict=None,
             theme='readthedocs',
-            theme_dir=None,
-            use_directory_urls=None,
-            site_dir=None
-        )
-
-    @mock.patch('mkdocs.config.load_config', autospec=True)
-    @mock.patch('mkdocs.commands.build.build', autospec=True)
-    def test_build_theme_dir(self, mock_build, mock_load_config):
-
-        result = self.runner.invoke(
-            cli.cli, ['build', '--theme-dir', 'custom'], catch_exceptions=False)
-
-        self.assertEqual(result.exit_code, 0)
-        self.assertEqual(mock_build.call_count, 1)
-        mock_load_config.assert_called_once_with(
-            config_file=None,
-            strict=None,
-            theme=None,
-            theme_dir='custom',
             use_directory_urls=None,
             site_dir=None
         )
@@ -329,7 +282,6 @@ def test_build_use_directory_urls(self, mock_build, mock_load_config):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=True,
             site_dir=None
         )
@@ -347,7 +299,6 @@ def test_build_no_directory_urls(self, mock_build, mock_load_config):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=False,
             site_dir=None
         )
@@ -365,7 +316,6 @@ def test_build_site_dir(self, mock_build, mock_load_config):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None,
             site_dir='custom',
         )
@@ -430,7 +380,6 @@ def test_gh_deploy_defaults(self, mock_gh_deploy, mock_build, mock_load_config):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None,
             site_dir=None
         )
@@ -515,7 +464,6 @@ def test_gh_deploy_remote_branch(self, mock_gh_deploy, mock_build, mock_load_con
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None,
             site_dir=None
         )
@@ -537,7 +485,6 @@ def test_gh_deploy_remote_name(self, mock_gh_deploy, mock_build, mock_load_confi
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None,
             site_dir=None
         )
@@ -591,7 +538,6 @@ def test_gh_deploy_strict(self, mock_gh_deploy, mock_build, mock_load_config):
             config_file=None,
             strict=True,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None,
             site_dir=None
         )
@@ -613,29 +559,6 @@ def test_gh_deploy_theme(self, mock_gh_deploy, mock_build, mock_load_config):
             config_file=None,
             strict=None,
             theme='readthedocs',
-            theme_dir=None,
-            use_directory_urls=None,
-            site_dir=None
-        )
-
-    @mock.patch('mkdocs.config.load_config', autospec=True)
-    @mock.patch('mkdocs.commands.build.build', autospec=True)
-    @mock.patch('mkdocs.commands.gh_deploy.gh_deploy', autospec=True)
-    def test_gh_deploy_theme_dir(self, mock_gh_deploy, mock_build, mock_load_config):
-
-        result = self.runner.invoke(
-            cli.cli, ['gh-deploy', '--theme-dir', 'custom'], catch_exceptions=False)
-
-        self.assertEqual(result.exit_code, 0)
-        self.assertEqual(mock_gh_deploy.call_count, 1)
-        self.assertEqual(mock_build.call_count, 1)
-        mock_load_config.assert_called_once_with(
-            remote_branch=None,
-            remote_name=None,
-            config_file=None,
-            strict=None,
-            theme=None,
-            theme_dir='custom',
             use_directory_urls=None,
             site_dir=None
         )
@@ -657,7 +580,6 @@ def test_gh_deploy_use_directory_urls(self, mock_gh_deploy, mock_build, mock_loa
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=True,
             site_dir=None
         )
@@ -679,7 +601,6 @@ def test_gh_deploy_no_directory_urls(self, mock_gh_deploy, mock_build, mock_load
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=False,
             site_dir=None
         )
@@ -701,7 +622,6 @@ def test_gh_deploy_site_dir(self, mock_gh_deploy, mock_build, mock_load_config):
             config_file=None,
             strict=None,
             theme=None,
-            theme_dir=None,
             use_directory_urls=None,
             site_dir='custom'
         )