doca-bootstrap-theme
v1.0.0
Published
Doca theme using Twitter Bootstrap
Downloads
3,433
Maintainers
lerwincf
lbarthonet
cf-media-manager
jacobbednarz
celso
cf-radar
dash_service_account
g4brym
snigdha34
wrangler-publisher
marksteyn
chiminator
sgoodhew_cf
terinjokes
third774
jsteinberger
jasnell
asapzacy
pcostanzo
gregbrimble
geelen
rexscaria
dcruz_cf
xuranwang
jculvey
sejoker
vasturiano
cf-ci-write
segments-write
thibmeu
xortive
gurjinder
cf-ci2
lvalenta
worengaKeywords
Readme
doca-bootstrap-theme
Simple Twitter Boostrap 3 based theme for doca.
It's supposed to be used in combination with doca - a tool that scaffolds API documentation based on JSON HyperSchemas.
Please file any issues at the doca repository.
Usage
npm install -g doca
doca init -t bootstrapThis creates a new API documentation with doca-bootstrap-theme as a dependency.
How to create your own theme
The best way is to fork and modify this repository. The integration with doca is pretty loose and it makes just a few assumptions about your theme.
React Components
Doca expects to import two React components from your theme (otherwise it fails):
App- main root component that gets all schemas through the propsHead-<head></head>part of the final documentation
App component
App component can expect to receive two props:
this.props.schemas: Immutable.List - an array of all imported schemas, the schema format can be found here - it's the ouput of json-schema-example-loader. However, the whole data structure is additionally turned into immutable one by Immutable.js library andImmutable.fromJS()function. It deeply converts all arrays into Immutable.List and all objects into Immutable.Map. Thus, you have to use slightly different methods for iteration or prop access.this.props.config: object - a plain object exported by users fromconfig.js, it should always have the keytitle.
Head component
Head component can expect to receive two props:
this.props.title: string - the title specified inconfig.jsthis.props.cssBundle: string - you should put this code into your Head component:{this.props.cssBundle && <link href={this.props.cssBundle} rel="stylesheet" />}
State
- You should just use native
this.stateand keep the state in your components. It's perfect for things like toggling. - Advanced: If your theme is getting bigger (a lot of state everywhere), you can consider using Redux. Doca is already using Redux for handling schemas. Your theme can export a reducer (check this pattern in our cf-ui components). However, it's up to you to modify the scaffolded application and import your reducer in
/src/client/reducers/index.js. Doca app currently doesn't do any assumptions about this (it could auto-import the theme reducer in future though). So if you want to make your theme useful out-of-the-box, try to use nativethis.stateinstead.
Global variables
You can use these three global variables (provided by webpack):
IS_JAVASCRIPT: bool - doca providesnpm run build:nojsscript. You can ship your API docs without JS bundle. This variable istruewhennojsflag is used. It gives you opportunity to do some changes in your components (show/hide sections should be visible by default etc.)LAST_MODIFIED: number -Date.now()value, in case you want to display "last modified" information somewhereprocess.env.NODE_ENV: enum - can bedevelopmentorproduction
Styles
You have three options how to style your React components:
- React inline styles.
- Link directly your external stylesheet in the Head component.
- Doca's webpack expects to find folder
/stylesin your theme. It dynamically imports and processes all css, less and scss files from this folder. Magic! Then, it bundles them into a single css file and passesthis.props.cssBundleto your Head component. You can leave this folder empty, thenthis.props.cssBundleis going to be empty.
Unfortunately, you can't directly import styles from your React components since webpack can't resolve such requires in node_modules.
Publishing
We would be happy to see more open source doca themes! Let us know if you publish some. It should follow this name convention:
doca-XXXXXXXX-themeTips
Immutable.js is used because resulting app (page) can be pretty big and we want to keep re-rendering fast. All your components should implement
shouldComponentUpdate()method, so it prevents unnecessary re-renders. Or you can simply extend your components from react-pure-render.When you're developing a new theme, you can streamline the process by copy&pasting your components into Doca app. That will give you hot-reloading! Otherwise, you can use npm link. With every change, you have to call
npm linkagain, so it triggersnpm prepublishand rebuilds your components (babel/JSX -> ES5).npm run lint(use node v4+)