Properly configure Google Analytics

[mhostetter]

This PR fixes #48 by properly assigning the config dictionary with the Google Analytics property value.

After some digging, I realized the Material for Mkdocs analytics code (partial) was not being added during local testing. The Google Analytics signaling I get on RTD is from custom JS added by RTD at build time.

Below is the partial looking for config.extra.analytics, which currently is not set.

sphinx-immaterial/src/partials/integrations/analytics/google.html

Lines 23 to 30 in 3b1a1a0

	<!-- Determine analytics property -->
	{% if config.extra.analytics %}
	{% set property = config.extra.analytics.property | d("", true) %}
	{% endif %}
	<!-- Google Analytics 4 (G-XXXXXXXXXX) -->
	{% if property.startswith("G-") %}
	<script>

I learned that the google_analytics configuration option has been deprecated in favor of extra/analytics. See here.

Current PR

This PR reads the old configuration style and assigns it properly in the config dictionary passed to the Material for Mkdocs pages. I tested this locally and it works -- the partial is added to the page and I can receive GA reports in my account, including search terms!

html_theme_options = {
    ...
    "google_analytics": ["G-XXXXXXXXXXXX", "auto"],
    ...
}

Future PR

However, I think it would be wise to adjust the html_theme_options hierarchy to match Material for Mkdocs configuration hierarchy. That is, I believe the html_theme_options should be:

html_theme_options = {
    ...
    "extra": {
        ...
        "analytics": {
            "provider": "google",
            "property": "G-XXXXXXXXXXX",
        }
        ...
    }
    ...
}

I noticed "social", "disqus", and "pwa_manifest" also don't have the property hierarchy. I believe they should be nested in the "extra" dictionary within html_theme_options.

sphinx-immaterial/sphinx_immaterial/__init__.py

Lines 228 to 248 in 3b1a1a0

	context.update(
	config=dict_merge(
	context.get("config", {}),
	{
	"theme": theme_options,
	"site_url": theme_options.get("site_url"),
	"site_name": context["docstitle"],
	"repo_url": theme_options.get("repo_url"),
	"repo_name": theme_options.get("repo_name", None),
	"extra": {
	"version": version_config,
	"social": theme_options.get("social"),
	"disqus": theme_options.get("disqus"),
	"manifest": theme_options.get("pwa_manifest"),
	},
	"plugins": theme_options.get("plugins"),
	"google_analytics": theme_options.get("google_analytics"),
	},
	),
	base_url=base_url,
	)

I'm willing to make this change and document it in a subsequent PR if you agree.

[2bndy5]

Thanks for looking into this! As for the config hierarchy, we're not going for exact duplication of the mkdocs theme. This is because of differences in implementation details. Generally, with sphinx, extensions get their own config variables (not a sub-section/field of a another theme-specific variable). But, there is going to be confusion about where the theme stops and the patchwork of extensions begins.

[mhostetter]

@2bndy5 how should I resolve the Black issues in the CI?

The GitHub Action says

Run black --check sphinx_immaterial/*.py
would reformat sphinx_immaterial/__init__.py

Oh no! 💥 💔 💥
1 file would be reformatted, 11 files would be left unchanged.

but locally it says this for me

matt@DESKTOP-I79NAGP:/mnt/c/Users/matth/repos/sphinx-immaterial$ black --check sphinx_immaterial/*.py
would reformat /mnt/c/Users/matth/repos/sphinx-immaterial/sphinx_immaterial/mermaid_diagrams.py
would reformat /mnt/c/Users/matth/repos/sphinx-immaterial/sphinx_immaterial/postprocess_html.py
would reformat /mnt/c/Users/matth/repos/sphinx-immaterial/sphinx_immaterial/inlinesyntaxhighlight.py
would reformat /mnt/c/Users/matth/repos/sphinx-immaterial/sphinx_immaterial/search_adapt.py
would reformat /mnt/c/Users/matth/repos/sphinx-immaterial/sphinx_immaterial/object_toc.py
would reformat /mnt/c/Users/matth/repos/sphinx-immaterial/sphinx_immaterial/content_tabs.py
would reformat /mnt/c/Users/matth/repos/sphinx-immaterial/sphinx_immaterial/__init__.py
would reformat /mnt/c/Users/matth/repos/sphinx-immaterial/sphinx_immaterial/apidoc_formatting.py
would reformat /mnt/c/Users/matth/repos/sphinx-immaterial/sphinx_immaterial/nav_adapt.py
All done! 💥 💔 💥
9 files would be reformatted, 3 files would be left unchanged.

Is there a config file I need to explicitly pass to black?

[2bndy5]

I think if you run black from the repo root it should automatically use the settings in the toml file

[2bndy5]

I don't see any specific black configuration in this repo. It might just be using a different version of black in the CI runner than what you're using locally.

[mhostetter]

Gotcha. I literally just installed black, so I'm sure I'm running the latest. And FWIW, I did run it in the repo root.

[mhostetter]

The CI says its uses Black 22.3.0 on Python 3.9. I have Python 3.8 and (the latest) Black 19.3b0.

It might be nice if there's a way to streamline this, or make it more consistent. Perhaps a CI action that appends a commit with the black formatting? Just a thought...

If I knew the black complaint, I'd manually reformat it...

[2bndy5]

We could have the output show a diff. I'm not very fluent on pre-commit (which is how you would go about automating black formatting). Also, it requires the dev to do frequent git pulls in the event that there was a pre-commit amendment...

[2bndy5]

The CI says its uses Black 22.3.0 on Python 3.9. I have Python 3.8 and (the latest) Black 19.3b0.

Unless I missed something, you're using an older version of black. Seems it left beta finally. Since they're using a time based symantic versioning, I'd wager 22.3.0 is newer than 19.3b0.

I suppose we could also pin to a specific black version in the requirements.txt file...

[mhostetter]

I would have thought the same... However, this is what I get. I'm guessing 19.3b0 is the latest for Python 3.8 and 22.3.0 is the latest for Python 3.9??

matt@DESKTOP-I79NAGP:/mnt/c/Users/matth/repos/sphinx-immaterial$ sudo apt install --upgrade black
[sudo] password for matt: 
Reading package lists... Done
Building dependency tree       
Reading state information... Done
black is already the newest version (19.3b0-1).

I can run the auto-formatter with the Black version I have, but I fear the newer(?) version will complain lol

[mhostetter]

Oops. I just realized that the Debain package isn't going to be the latest. I ran pip install black, as is done in the CI, and I'm getting the same version. Sorry for the confusion, @2bndy5 !!

[2bndy5]

oh yeah, getting updated resources from apt typically isn't a thing. 🤣

[mhostetter]

I think this PR is ready. Does this look good to you, @jbms?

[jbms]

Maybe we should just have an analytics theme option that just matches mkdocs-material rather than using a different syntax?

I don't see a particular advantage to doing it differently.

[mhostetter]

I added an "analytics" options to html_theme_options, as suggested. I also left the parser of the old style of configuration in case it's passed, for backwards compatibility.

I also updated the docs. Let me know your thoughts, or if you'd me like to change anything.

[jbms]

Thanks!