Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MkDocs projects use RTD's analytics privacy improvements #4013

Merged

Conversation

@davidfischer
Copy link
Contributor

@davidfischer davidfischer commented Apr 24, 2018

Read the Docs has implemented some privacy enhancements for authors who opt to enable Google Analytics on their projects. This change enables those for MkDocs projects.

For example, the mkdocs project (a documentation project that uses mkdocs itself) specifies their own Google Analytics code in their mkdocs.yml. When MkDocs builds the docs, the Google analytics snippet is injected directly into the output. However, Read the Docs already supports user GA analytics codes and has enabled some improvements around there such as anonymizing visitor IPs. Without this change, MkDocs projects bypass these protections which can result in reduced privacy or possibly double counting in analytics (if the analytics code is specified in RTD and in mkdocs.yml). By hooking into the RTD setup, we can enable those privacy enhancements for people who specify their Google Analytics setup in mkdocs.yml and ensure there's no double counting.

@davidfischer davidfischer added this to the Mkdocs milestone Apr 24, 2018
Copy link
Member

@ericholscher ericholscher left a comment

Looks good. I do worry about changing the order of this code in the future and clobbering the google_analytics on the user_config before we read it, but I don't know a good way around that.

docs_path = os.path.join(self.root_path, docs_dir)

# RTD javascript writing
rtd_data = self.generate_rtd_data(docs_dir=docs_dir, mkdocs_config=user_config)
with open(os.path.join(docs_path, 'readthedocs-data.js'), 'w') as f:
f.write(rtd_data)

# Use Read the Docs' analytics setup rather than mkdocs'
# This supports using RTD's privacy improvements around analytics
user_config['google_analytics'] = None
Copy link
Member

@ericholscher ericholscher Apr 25, 2018

Should we delete this, instead of setting it to None?

Copy link
Contributor Author

@davidfischer davidfischer Apr 26, 2018

I use del extremely rarely, but I don't have a particularly strong opinion.

analytics_code = self.version.project.analytics_code
if not analytics_code and mkdocs_config.get('google_analytics'):
# http://www.mkdocs.org/user-guide/configuration/#google_analytics
analytics_code = mkdocs_config['google_analytics'][0]
Copy link
Member

@ericholscher ericholscher Apr 25, 2018

Is this always a list? Feels a bit brittle and might just grab one character if it's just a string.

Copy link
Contributor Author

@davidfischer davidfischer Apr 26, 2018

The docs link leads me to believe it is a list. I'm fine being a bit more defensive here.

Copy link
Contributor Author

@davidfischer davidfischer Apr 27, 2018

Actually, it looks like that is probably unnecessary: https://github.com/mkdocs/mkdocs/blob/71ebf35/mkdocs/config/defaults.py#L51-L53

Copy link
Contributor Author

@davidfischer davidfischer Apr 27, 2018

It is guaranteed to be either null or a 2-tuple

Copy link
Member

@ericholscher ericholscher Apr 27, 2018

👍

@ericholscher ericholscher merged commit 2bc8084 into readthedocs:master Apr 27, 2018
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants