From 675d6874bd4e828184654e95b78665749c8606ca Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Sun, 22 May 2022 13:27:28 -0700 Subject: [PATCH 1/2] Port from recommonmark to myst-parser Refs https://github.com/readthedocs/recommonmark/issues/221 --- docs/blog/newsletter-december-2016.md | 9 ++++----- docs/blog/newsletter-march-2017.md | 8 ++++---- docs/blog/newsletter-november-2016.md | 9 ++++----- docs/blog/newsletter-october-2016.md | 9 ++++----- docs/blog/newsletter-september-2016.md | 21 ++++++--------------- docs/conf.py | 10 ++-------- requirements.txt | 16 ++++++++++++---- 7 files changed, 36 insertions(+), 46 deletions(-) diff --git a/docs/blog/newsletter-december-2016.md b/docs/blog/newsletter-december-2016.md index 1c4b88082b..ee386bcdfc 100644 --- a/docs/blog/newsletter-december-2016.md +++ b/docs/blog/newsletter-december-2016.md @@ -1,8 +1,7 @@ -```eval_rst - -.. post:: Dec 5, 2016 - :tags: newsletter - +```{post} Dec 5, 2016 +--- +tags: newsletter +--- ``` # Write the Docs Newsletter - December 2016 diff --git a/docs/blog/newsletter-march-2017.md b/docs/blog/newsletter-march-2017.md index c7540e517f..78cc185a1b 100644 --- a/docs/blog/newsletter-march-2017.md +++ b/docs/blog/newsletter-march-2017.md @@ -1,7 +1,7 @@ -```eval_rst - -.. post:: Mar 14, 2017 - :tags: newsletter, march, formatting, bylines, alt text, job titles, community +```{post} Mar 14, 2017 +--- +tags: newsletter, march, formatting, bylines, alt text, job titles, community +--- ``` diff --git a/docs/blog/newsletter-november-2016.md b/docs/blog/newsletter-november-2016.md index d08dd505c8..0e541161f7 100644 --- a/docs/blog/newsletter-november-2016.md +++ b/docs/blog/newsletter-november-2016.md @@ -1,7 +1,7 @@ -```eval_rst - -.. post:: Nov 3, 2016 - :tags: newsletter, november, +```{post} Nov 3, 2016 +--- +tags: newsletter, november, +--- ``` @@ -62,7 +62,6 @@ All of that said, a handful of solutions and platforms were mentioned in the con * [Forestry](https://forestry.io/) – builds a CMS from a repo of your Jekyll or Hugo project * [CraftCMS](https://craftcms.com) – user-friendly CMS, handy if you have non-techy folks contributing to your docs - ## Using abbreviations and acronyms in documentation What started as a quick poll about how to abbreviate "input/output" – 'I/O' won handily over 'IO', 18:3 — quickly turned into a broader discussion about abbreviations in documentation on the whole. Here were some of the key questions and takeaways that emerged: diff --git a/docs/blog/newsletter-october-2016.md b/docs/blog/newsletter-october-2016.md index 1b9748eeba..5b27e1b6e0 100644 --- a/docs/blog/newsletter-october-2016.md +++ b/docs/blog/newsletter-october-2016.md @@ -1,7 +1,7 @@ -```eval_rst - -.. post:: Oct 3, 2016 - :tags: newsletter +```{post} Oct 3, 2016 +--- +tags: newsletter +--- ``` @@ -33,7 +33,6 @@ None of these are a perfect solution, perhaps, but they all give us somewhere to To help us with questions like the one above, Thursday Bram (@thursday) (one of our illustrious WtD speakers) and Audrey Eschright (founder and publisher of _[The Recompiler](https://recompilermag.com/)_) just successfully funded their Kickstarter campaign to publish the [Responsible Communication Guide](https://www.kickstarter.com/projects/961164339/the-responsible-communication-style-guide). The project will produce a cross-functional style guide to help people write about technology in way that is more sensitive and inclusive around questions of race, gender, sexuality, religion, and health. Definitely a project to keep an eye on—congratulations to everyone who worked so hard to get it funded! - ## Writing and maintaining command reference pages On the technical side of things, early in the month a bunch of folks tackled the question of how best to put together command reference pages. For example, take a look at [http://redis.io/commands](http://redis.io/commands), [https://developer.wordpress.org/cli/commands/](https://developer.wordpress.org/cli/commands/), or [https://drushcommands.com/](https://drushcommands.com/). diff --git a/docs/blog/newsletter-september-2016.md b/docs/blog/newsletter-september-2016.md index 8d585f410c..81c6b6ec2b 100644 --- a/docs/blog/newsletter-september-2016.md +++ b/docs/blog/newsletter-september-2016.md @@ -1,8 +1,7 @@ -```eval_rst - -.. post:: Sep 1, 2016 - :tags: newsletter - +```{post} Sep 1, 2016 +--- +tags: newsletter +--- ``` # Write the Docs Newsletter - September 2016 @@ -13,18 +12,12 @@ Hello Write the Docs! If you're getting this email, you've probably attended (or As part of that effort, we're sending you this, our inaugural edition of the new Write the Docs monthly newsletter! Our goal is to make it easier for folks to keep current with what the community's talking about each month. The bulk of the newsletter content will be distilled from interesting conversations that crop up on the #general channel of the [Write the Docs Slack ](http://slack.writethedocs.org/). We'll be highlighting topics that are recurring themes or simply seem to resonate with a lot of folks. -```eval_rst -.. note:: We know the #general channel is just one arena for docs talk. If you see a conversation elsewhere on Slack (or Twitter or wherever) that would make good newsletter fodder, ping our editor, `Kelly O'Brien `_. +```{note} +We know the #general channel is just one arena for docs talk. If you see a conversation elsewhere on Slack (or Twitter or wherever) that would make good newsletter fodder, ping our editor, [Kelly O'Brien](https://www.writethedocs.org/team/#newsletter-team). ``` -```eval_rst - -.. only:: email - - If this sounds like fun, awesome! Consider yourself subscribed! If you'd rather keep our emails limited to just conference-related notices, that's fine too. Just `click here to select which emails you get <*|UPDATE_PROFILE|*>`_ from the newsletter list. -``` And without further ado, here's a few topics of conversation from this past month that tickled our fancy: @@ -43,13 +36,11 @@ There were also a handful of great suggestions for UI copy best practices: If you're looking for more info about UI help text, check out Beth Aitman's talk on the subject from Write the Docs EU 2015. For more on progressive disclosure, try this blog post: [Masking Complexity through Progressive Disclosure](https://blog.recurly.com/2013/04/masking-complexity-through-progressive-disclosure), - ## Metrics case study: Total Time Reading (TTR) Who doesn't love talking about documentation metrics? (No one, that's who.) One of the Write the Docs co-founders, Troy Howard, has a new blog post out, in which he takes a close look at Total Time Reading (TTR) as a way of judging the success of a page or article. If documentation metrics is your thing, it's definitely worth a read: [TechDocs Metrics Case Study: Total Time Reading (TTR)](http://blog.thoward37.me/articles/techdocs-metrics-total-time-reading-(ttr)) - ## Code review versus copy review Another blog post that spurred conversation was this one from the Atlassian blog, [The (written) unwritten guide to pull requests](http://blogs.atlassian.com/2016/07/written-unwritten-guide-pull-requests/). In addition to having lots of good pointers for, y'know, doing code reviews, it also sparked a conversation about some of those same techniques can be used to conduct copy reviews on your docs. diff --git a/docs/conf.py b/docs/conf.py index 4b5052a608..2a1d2075ce 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,7 +6,6 @@ import yaml import ablog -from recommonmark.transform import AutoStructify # Only for windows compatibility - Forces default encoding to UTF8, which it may not be on windows if os.name == 'nt': @@ -64,8 +63,9 @@ 'sphinxcontrib.datatemplates', 'notfound.extension', 'sphinxemoji.sphinxemoji', - 'recommonmark', + 'myst_parser', ] + blog_baseurl = 'https://www.writethedocs.org/' blog_path = 'blog/archive' blog_authors = { @@ -199,12 +199,6 @@ def setup(app): app.add_directive('meetup-listing', MeetupListing) app.add_directive('datatemplate-video', videos.DataTemplateVideo) - app.add_config_value('recommonmark_config', { - 'auto_toc_tree_section': 'Contents', - # 'enable_auto_doc_ref': True, - 'enable_eval_rst': True, - }, True) - app.add_transform(AutoStructify) app.add_css_file('css/global-customizations.css') app.add_css_file('css/survey.css') app.add_js_file('js/jobs.js') diff --git a/requirements.txt b/requirements.txt index 33348a0e5b..11f35cc636 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,10 +1,19 @@ Sphinx==4.5.0 -recommonmark==0.7.1 -ablog==0.10.6 # pyup: ignore + +# make livehtml support sphinx_autobuild==2021.3.14 -PyYAML>=4.2b1 + +# Markdown support +myst-parser==0.17.2 + +# Blogging +ablog==0.10.6 # pyup: ignore + # Sphinx (checked with 4.3) requires docutils=<0.18 docutils==0.17.1 # pyup: <0.18 +PyYAML>=4.2b1 + +# Additional libraries csvkit==1.0.7 yamllint==1.26.3 pathlib==1.0.1 @@ -21,4 +30,3 @@ sphinxemoji==0.2.0 Werkzeug==0.16.1 # pyup: <1.0 # For fancy 404 pages sphinx-notfound-page==0.8 - From aa26121fb0aca881eb9112e9764e01912a31d8ab Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Sun, 22 May 2022 13:40:53 -0700 Subject: [PATCH 2/2] Fix lint warnings --- docs/conf.py | 2 ++ docs/hiring-guide/freelancing/business-identity.md | 11 +++++------ docs/hiring-guide/freelancing/business-plan.md | 13 ++++++------- docs/news/call_for_organizers.md | 2 +- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 2a1d2075ce..4dac33050b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,6 +66,8 @@ 'myst_parser', ] +myst_heading_anchors = 4 + blog_baseurl = 'https://www.writethedocs.org/' blog_path = 'blog/archive' blog_authors = { diff --git a/docs/hiring-guide/freelancing/business-identity.md b/docs/hiring-guide/freelancing/business-identity.md index 4abc37e51b..d46574b430 100644 --- a/docs/hiring-guide/freelancing/business-identity.md +++ b/docs/hiring-guide/freelancing/business-identity.md @@ -10,9 +10,8 @@ Your business identity is how you position yourself in the market, and your corp "I love the startup vibe." #### Related -[Core values > What sort of work do I want to do?](../core-values#what-sort-of-work-do-i-want-to-do) -[Core values > Where do I want to work?](../core-values#where-do-i-want-to-work) - +[Core values > What sort of work do I want to do?](core-values.md#what-sort-of-work-do-i-want-to-do) +[Core values > Where do I want to work?](core-values.md#where-do-i-want-to-work) ### How do I present myself to the world / what is the tone of my interaction with clients? @@ -21,8 +20,8 @@ Your business identity is how you position yourself in the market, and your corp "I will adapt to each client's tone." #### Related -[Core values > What sort of relationship do I want with my clients?](../core-values#what-sort-of-relationship-do-i-want-with-my-clients) -[Core values > How much of myself do I want in my work?](../core-values#how-much-of-myself-do-i-want-in-my-work) +[Core values > What sort of relationship do I want with my clients?](core-values.md#what-sort-of-relationship-do-i-want-with-my-clients) +[Core values > How much of myself do I want in my work?](core-values.md#how-much-of-myself-do-i-want-in-my-work) ### What do I offer my client? @@ -34,7 +33,7 @@ Think about your value proposition. Be specialized: the clearer you are about yo #### Related -[Core values > What sort of work do I want to do?](../core-values#what-sort-of-work-do-i-want-to-do) +[Core values > What sort of work do I want to do?](core-values.md#what-sort-of-work-do-i-want-to-do) ### What tools do I specialize in? diff --git a/docs/hiring-guide/freelancing/business-plan.md b/docs/hiring-guide/freelancing/business-plan.md index 9c7f7a66f1..36705d9d79 100644 --- a/docs/hiring-guide/freelancing/business-plan.md +++ b/docs/hiring-guide/freelancing/business-plan.md @@ -12,9 +12,9 @@ Your business plan is the practical implementation of the [values](core-values.m #### Related -[Core values > What sort of work do I want to do?](../core-values#what-sort-of-work-do-i-want-to-do) -[Core values > Where do I want to work?](../core-values#where-do-i-want-to-work) -[Business identity > What type of clients do I want?](../business-identity#what-type-of-clients-do-i-want) +[Core values > What sort of work do I want to do?](core-values.md#what-sort-of-work-do-i-want-to-do) +[Core values > Where do I want to work?](core-values.md#where-do-i-want-to-work) +[Business identity > What type of clients do I want?](business-identity.md#what-type-of-clients-do-i-want) [Finding work](find-work.md) ### What are my rates? @@ -39,7 +39,7 @@ A range of factors contribute to your rates: #### Related -[Business identity > What type of clients do I want?](../business-identity#what-type-of-clients-do-i-want) +[Business identity > What type of clients do I want?](business-identity.md#what-type-of-clients-do-i-want) ### Where do I want to be in *X* years? @@ -50,9 +50,8 @@ A range of factors contribute to your rates: #### Related -[Core values > Why do I want to freelance?](../core-values#why-do-i-want-to-freelance) -[Core values > What is my key motivator?](../core-values#what-is-my-key-motivator) - +[Core values > Why do I want to freelance?](core-values.md#why-do-i-want-to-freelance) +[Core values > What is my key motivator?](core-values.md#what-is-my-key-motivator) ## Template diff --git a/docs/news/call_for_organizers.md b/docs/news/call_for_organizers.md index ddea39f9bd..456ff73e17 100644 --- a/docs/news/call_for_organizers.md +++ b/docs/news/call_for_organizers.md @@ -8,7 +8,7 @@ but it takes some additional planning and it will help if you have some familiar Said familiarity is not required, but if you don't know DC, it could affect the organizer roles that make sense for you to assume. -### Location and Venue +# Location and Venue Jennifer Rondeau, co-organizer of WTD NA in Portland for two years now, recently moved to DC, and is willing to be organizer in chief on the ground, so the DC area might make the most sense.