From 228c6a92131c91c9a8cf47f16454746487be316f Mon Sep 17 00:00:00 2001 From: Paul McLanahan Date: Fri, 10 Sep 2021 11:40:33 -0400 Subject: [PATCH] Fix docs formating errors and warnings from Sphinx --- docs/coding.rst | 1 + docs/contentful.rst | 59 ++++++++++++++++++++-------------------- docs/index.rst | 1 + docs/install.rst | 2 +- docs/javascript-libs.rst | 6 +++- 5 files changed, 38 insertions(+), 31 deletions(-) diff --git a/docs/coding.rst b/docs/coding.rst index 321db76ac3..d8e25226bb 100644 --- a/docs/coding.rst +++ b/docs/coding.rst @@ -315,6 +315,7 @@ define URLs per country as well as a default for everyone else. } default_url = 'app.everyone-else' + In this example people in Canada would go to the URL that Django returns using `reverse()` (i.e. the name of the URL) and everyone else would go to the `app.everyone-else` URL. You may also use full URLs instead of URL names if you want to. It will look for strings that diff --git a/docs/contentful.rst b/docs/contentful.rst index 7e2ba57c3a..41daa9aa72 100644 --- a/docs/contentful.rst +++ b/docs/contentful.rst @@ -4,9 +4,9 @@ .. _contentful: -=========== +====================== Contentful Integration -=========== +====================== Overview -------- @@ -28,7 +28,7 @@ correspond to components in our design system. The smallest create little bits o like buttons. The larger ones group together several entries for the smaller components into a bigger component or an entire page. -For example: The _Page: General_ model allows editors to include a hero entry, body +For example: The *Page: General* model allows editors to include a hero entry, body entry, and callout entry. The callout layout entry, in turn, includes a CTA entry. @@ -173,7 +173,7 @@ display image to a regular card entry. The large card must still be included in Layout: 5 Cards. ✏️ Component -~~~~~~~~~~~ +~~~~~~~~~~~~ We're using this term pretty loosely. It corresponds roughly to a Protocol atom, molecule, or organism. @@ -195,28 +195,28 @@ however, they don't have a specific layout wrapper either. They can go in any en has a body field that is configured as rich text (picto, split, multi column text...) Adding a new ✏️ Component -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~ Example: Picto -#. Create the content model in Contentful -_Follow the naming conventions._ -You may need two models if you are configuring layout separately. -#. Add the new content model to the list of allowed references in other content models -(ATM this is just the "content" reference field on pages). -#. In bedrock create CSS and JS entries in static-bundles for the new component. -#. In api.py write a def for the component -#. In api.py add the component name, def, and bundles to the CONTENT_TYPE_MAP -#. Find or add the macro to macros-protocol -#. Import the macro into all.html and add a call to it in the entries loop +#. Create the content model in Contentful. + * *Follow the naming conventions*. + * You may need two models if you are configuring layout separately. + +#. Add the new content model to the list of allowed references in other content models (ATM this is just the "content" reference field on pages). +#. In bedrock create CSS and JS entries in static-bundles for the new component. +#. In api.py write a def for the component. +#. In api.py add the component name, def, and bundles to the CONTENT_TYPE_MAP. +#. Find or add the macro to macros-protocol. +#. Import the macro into all.html and add a call to it in the entries loop. .. note:: - Tips: - - can't define defaults in Contentful, so set those in your Python def - - for any optional fields make sure you check the field exists before referencing the - content + Tips: + + * can't define defaults in Contentful, so set those in your Python def. + * for any optional fields make sure you check the field exists before referencing the content. Adding a new ♟ Component @@ -224,19 +224,20 @@ Adding a new ♟ Component Example: Wordmark. -#. Create the content model in Contentful -_Follow the naming conventions._ -#. Add the new content model to rich text fields (like split and text) -#. In bedrock include the CSS in the Sass file for any component which may use it. -(yeah, this is not ideal, hopefully we will have better control in the future) -#. Add a def to api.py to render the piece (like _make_wordmark) +#. Create the content model in Contentful. + + * *Follow the naming conventions*. + +#. Add the new content model to rich text fields (like split and text). +#. In bedrock include the CSS in the Sass file for any component which may use it (yeah, this is not ideal, hopefully we will have better control in the future). +#. Add a def to api.py to render the piece (like ``_make_wordmark``). .. note:: - Tips: - - can't define defaults in Contentful, so set those in your Python def - - for any optional fields make sure you check the field exists before referencing the - content + Tips: + + * can't define defaults in Contentful, so set those in your Python def. + * for any optional fields make sure you check the field exists before referencing the content. Adding a rich text field in a component ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/index.rst b/docs/index.rst index 8e1fef0bc9..22861b0b03 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,6 +32,7 @@ Contents redirects javascript-libs newsletters + contentful content-cards banners uitour diff --git a/docs/install.rst b/docs/install.rst index 81d5a6706d..5d540e305f 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -233,8 +233,8 @@ image first: .. code-block:: bash $ make build-prod run-prod -Localization +Localization ============ Localization (or L10n) files were fetched by the `bootstrap.sh` command your ran earlier and are diff --git a/docs/javascript-libs.rst b/docs/javascript-libs.rst index 3ed58524fe..22d617b365 100644 --- a/docs/javascript-libs.rst +++ b/docs/javascript-libs.rst @@ -11,4 +11,8 @@ JavaScript Libraries Mozilla Image Lazy Loader ------------------------- -:ref:`mozilla-lazy-load.js` + +.. toctree:: + :maxdepth: 2 + + mozilla-lazy-load