docs: document ThemeProvider override functionality

Author: quantizor

sections/api/primary/theme-provider.mdx

@@ -13,12 +13,14 @@ Check the section on [Theming](/docs/advanced#theming).
       <Code>theme</Code>
     </Column>
     <Column>
-      An object that will be injected as <Code>theme</Code> into all
+      An object (or function returning an object) that will be injected as <Code>theme</Code> into all
       interpolations in styled components beneath the provider.
     </Column>
   </Row>
 </Table>
 
+Simple usage:
+
 ```react
 // import styled, { ThemeProvider } from 'styled-components'
 
@@ -32,3 +34,25 @@ render(
   </ThemeProvider>
 )
 ```
+
+Adding to or replacing an outer theme using nested `ThemeProvider`:
+
+```react
+// import styled, { ThemeProvider } from 'styled-components'
+
+const Box = styled.div`
+  background-color: ${props => props.theme.bg};
+  color: ${props => props.theme.color};
+`
+
+render(
+  <ThemeProvider theme={{ bg: 'white', color: 'mediumseagreen' }}>
+    <Box>
+      I'm mediumseagreen with a white background!
+      <ThemeProvider theme={outerTheme => ({...outerTheme, bg: 'black'})}>
+        <Box>I'm mediumseagreen with a black background!</Box>
+      </ThemeProvider>
+    </Box>
+  </ThemeProvider>
+)
+```