docs: Updating README with repository details. (#122)

* docs: Specify component usage requirements in the README. This includes both the component's dependency on @edx/frontend-platform, as well as its required environment variables. * docs: fix verbatim formatting * docs: improving footer README Including headings and formatting consistent with frontend-component-header. Hopefully others soon.
2021-05-14 12:57:09 -04:00
parent 1b6a5eda0b
commit c756f42c28
1 changed files with 76 additions and 42 deletions
--- a/README.rst
+++ b/README.rst
@@ -1,61 +1,95 @@
+#########################
 frontend-component-footer
-=========================
+#########################

-|Build Status| |Coveralls| |npm_version| |npm_downloads| |license|
-|semantic-release|
+|Build Status| |Codecov| |npm_version| |npm_downloads| |license| |semantic-release|

-frontend-component-footer is a library containing a site footer
-component for use when building Open edX frontend applications.
-
-Usage
-----
-
-To install frontend-component-footer into your project::
-
-   npm i --save @edx/frontend-component-footer
-
-Component Usage::
-
-   import Footer, { messages } from '@edx/frontend-component-footer';
-
-   ...
-
-   <Footer
-      onLanguageSelected={(languageCode) => {/* set language */}}
-      supportedLanguages={[
-         { label: 'English', value: 'en'},
-         { label: 'Español', value: 'es' },
-      ]}
-   />
-
- onLanguageSelected (optional)
- supportedLanguages (optional)
-
-Styles (project.scss)::
-
-   @import '@edx/frontend-component-footer/src/footer.scss';
+********
+Overview
+********

+A generic footer for Open edX micro-frontend applications.  It includes a logo and an optional language selector dropdown.

+************
 Requirements
------------
+************

-This component uses ``@edx/frontend-i18n``. Any containing app must provide ``@edx/frontend-i18n`` as a peer dependency, and be wrapped inside an ``IntlProvider`` element, whether or not your consuming application is actually localized. For a basic default locale (English) version, follow the ``IntlProvider`` example in the sample application in `src/index.jsx <src/index.jsx>`__.
+This component uses ``@edx/frontend-platform`` services such as i18n, analytics, configuration, and the ``AppContext`` React component, and expects that it has been loaded into a micro-frontend that has been properly initialized via ``@edx/frontend-platform``'s ``initialize`` function.  `Please visit the frontend template application to see an example. <https://github.com/edx/frontend-template-application/blob/3355bb3a96232390e9056f35b06ffa8f105ed7ca/src/index.jsx>`_

+Environment Variables
+=====================
+
+This component requires that the following environment variable be set by the consuming micro-frontend.
+
+* ``LOGO_TRADEMARK_URL`` - This is a URL to a logo for use in the footer.  This is a different environment variable than ``LOGO_URL`` (used in frontend-component-header) to accommodate sites that would like to have additional trademark information on a logo in the footer, such as a (tm) or (r) symbol.
+
+************
+Installation
+************
+
+To install this footer into your Open edX micro-frontend, run the following command in your MFE:
+
+``npm i --save @edx/frontend-component-footer``
+
+This will make the component available to be imported into your application.
+
+*****
+Usage
+*****
+
+This library has the following exports:
+
+* ``(default)``: The footer as a React component.
+* ``messages``: Internationalization messages suitable for use with `@edx/frontend-platform/i18n <https://edx.github.io/frontend-platform/module-Internationalization.html>`_
+* ``dist/footer.scss``: A SASS file which contains style information for the component.  It should be imported into the micro-frontend's own SCSS file.
+
+<Footer /> component props
+==========================
+
+* onLanguageSelected: Provides the footer with an event handler for when the user selects a
+  language from its dropdown.
+* supportedLanguages: An array of objects representing available languages.  See example below for object shape.
+
+Examples
+========
+
+Component Usage Example::
+
+  import Footer, { messages } from '@edx/frontend-component-footer';
+
+  ...
+
+  <Footer
+    onLanguageSelected={(languageCode) => {/* set language */}}
+    supportedLanguages={[
+      { label: 'English', value: 'en'},
+      { label: 'Español', value: 'es' },
+    ]}
+  />
+
+* `An example of minimal component and messages usage. <https://github.com/edx/frontend-template-application/blob/3355bb3a96232390e9056f35b06ffa8f105ed7ca/src/index.jsx#L23>`_
+* `An example of SCSS file usage. <https://github.com/edx/frontend-template-application/blob/3cd5485bf387b8c479baf6b02bf59e3061dc3465/src/index.scss#L9>`_
+
+***********
 Development
-----------
+***********

-Start the dev server::
+Install dependencies::

-   npm i && npm start
+  npm i

-Build the component::
+Start the development server::

-   npm run build
+  npm start
+
+Build a production distribution::
+
+  npm run build

 .. |Build Status| image:: https://api.travis-ci.com/edx/frontend-component-footer.svg?branch=master
   :target: https://travis-ci.com/edx/frontend-component-footer
-.. |Coveralls| image:: https://img.shields.io/coveralls/edx/frontend-component-footer.svg?branch=master
-   :target: https://coveralls.io/github/edx/frontend-component-footer
+.. |Codecov| image:: https://img.shields.io/codecov/c/github/edx/frontend-component-footer
+   :target: @edx/frontend-component-footer
 .. |npm_version| image:: https://img.shields.io/npm/v/@edx/frontend-component-footer.svg
   :target: @edx/frontend-component-footer
 .. |npm_downloads| image:: https://img.shields.io/npm/dt/@edx/frontend-component-footer.svg