@addaps/doca-addaps-theme 中文文档教程
doca-bootstrap-theme
Twitter Boostrap 3 的 doca 主题。
它应该与 doca 结合使用 - 一种基于 JSON HyperSchemas 构建 API 文档的工具。
请在 doca 存储库中提交任何问题。
Usage
npm install -g doca
doca init -t bootstrap
这将创建一个新的 API 文档，并将 doca-bootstrap-theme 作为依赖项。
How to create your own theme
最好的方法是分叉和修改此存储库。与 doca 的集成非常松散，它只对您的主题做出一些假设。
React Components
Doca 希望从您的主题中导入两个 React 组件（否则会失败）：
App- main root component that gets all schemas through the propsHead-<head></head>part of the final documentation
App component
App component 可以期望收到两个道具：
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 可以期望收到两个 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
你可以使用这三个全局变量（由 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
你有三个选项如何设置你的 React 组件的样式：
- 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.
不幸的是，你不能直接从你的 React 组件导入样式因为 webpack 无法解决 node_modules 中的此类要求。
Publishing
我们很高兴看到更多开源 doca 主题！ 如果您发布了一些，请告诉我们。 它应该遵循这个命名约定：
doca-XXXXXXXX-theme
Tips
使用 Immutable.js 是因为生成的应用程序（页面）可能非常大，我们希望保持快速重新渲染。 您的所有组件都应该实现
shouldComponentUpdate()方法，这样可以防止不必要的重新渲染。 或者您可以简单地从 react-pure-render 扩展您的组件。在开发新主题时，您可以通过将组件复制并粘贴到 Doca 应用程序来简化流程。 那会给你热重装！ 否则，您可以使用 npm 链接。 每次更改时，您都必须再次调用
npm link，因此它会触发npm prepublish并重建您的组件（babel/JSX -> ES5）。npm run lint（使用节点 v4+）
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 bootstrap
This 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-theme
Tips
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+)
你可能也喜欢
- @1amageek/tradestore 中文文档教程
- @36node/redux-cron 中文文档教程
- @4geit/swg-mock-data-helper 中文文档教程
- @51npm/freedom-middleware-webpack2 中文文档教程
- @abcum/ember-gridlist 中文文档教程
- @abetomo/simply-imitated-sqs 中文文档教程
- @abramltd/jwt-oauth2-middleware 中文文档教程
- @absolunet/gulp-include 中文文档教程
- @abtasty/product-image-optimization 中文文档教程
- @abuffseagull/eslint-config-base 中文文档教程
