carbon-io / carbon-io Goto Github PK

I was building the docs and ran into an error:

Exception occurred:
  File "conf.py", line 418, in patch_object_description
    app.domains['js'].roles['class'] = JSXRefRole()
AttributeError: 'Sphinx' object has no attribute 'domains'

When I comment out line 418 in docs/common/conf.py it seems to build okay.

The comment above that line says "Patch Javascript domain to remove parens on class refs". What does that mean exactly?

This may be intended, but it seems unintuitive that / matches root, but /route will not match /route URI in endpoint declarations. Is there a reason we don't support both route and /route?

Hey carbon.io maintainers. I've been watching this project for a while now and I'm wondering if this is ready for production usage. I think I saw a caveat earlier to avoid prod use until 1.0. Is that still the case? Is there a timeline on when that milestone will be achieved? Thanks!

Was thinking about a way of having a simpler require statement. We can change this:

var carbon = require('carbon-io')
var o  = carbon.atom.o(module).main
var __ = carbon.fibers.__(module)

to something like this:

const {carbond, o, __} = require('carbon-io')(module);

If we change carbon-io to export like this:

var core = require('@carbon-io/carbon-core')

module.exports = (mod) => {
  return {
    atom: core.atom,
    bond: core.bond,
    fibers: core.fibers,
    carbond: require('@carbon-io/carbond'),
    ejson: core.ejson,
    leafnode: core.leafnode,
    testtube: core.testtube,
    HttpErrors: core.HttpErrors,

    // added lines:

    o: core.atom.o(mod).main,
    __: core.fibers.__(mod)
  }
}

Not a perfect way of doing it - this is just a POC. I think it will make documentation and examples a little easier. Just have to add one line to examples and it's all runnable rather than having these rather bulky require statements.

Thoughts?

Good morning,
I am evaluating the Carbon:io library to see if it fit my needs: create reports in excel and word based on data generated via GraphQL.
I must say that my first test are very positive.
I am, anyway, facing some problem in converting a numeric result into a real number in excel.

I have seen that the Carbon documentation reports several Formatters for date and string but not for numbers.
Do you know if there is something like convInt, confFloat I could sue in my template?

Thank you in advance for your help,
Best Regards,
M.

add carbon-core package and hang atom, bond, fibers, etc... off that. update carbond and carbon-io to point to carbon-core

• Home should be to the docs for now
• Docs should be to the docs
• Tutorials replaced by Examples (for now)
• Github to the organization page
• Support to the Support section of the docs

currently each project has it's own _static folder, which contains CSS, JS, etc.. for example:

https://github.com/carbon-io/carbon-io/tree/master/docs/_static
https://github.com/carbon-io/carbond/tree/master/docs/_static

how should we structure this?

var __ = carbon.fibers.__(module).main is still used in a lot of code snippets. As I understand it, that's been deprecated.

this is not consistent across carbon-io sub-projects

Running node lib/PublicStatusApi.js gen-static-docs --flavor github-flavored-markdown on the latest tag (0.1.14), results in the following stacktrace:

╰─$ node lib/PublicStatusApi.js gen-static-docs --flavor github-flavored-markdown
{ [Error: Cannot find module './build/Release/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }
{ [Error: Cannot find module './build/default/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }
{ [Error: Cannot find module './build/Debug/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }
WARNING: carbon-io/fiber is deprecated. Use carbon-io/fibers instead
Error: Error loading module: /Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/carbond/lib/docgen/StaticDocumentation.js Error: Cannot find module 'fibrous'
    at Function.Module._resolveFilename (module.js:325:15)
    at Function.Module._load (module.js:276:25)
    at Module.require (module.js:353:17)
    at require (internal/module.js:12:17)
    at Object.<anonymous> (/Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/carbond/lib/docgen/GitHubMarkDown.js:4:15)
    at Module._compile (module.js:409:26)
    at Object.Module._extensions..js (module.js:416:10)
    at Module.load (module.js:343:32)
    at Function.Module._load (module.js:300:12)
    at Module.require (module.js:353:17)
    at require (internal/module.js:12:17)
    at resolveModule (/Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/carbond/node_modules/bond/lib/bond.js:60:11)
    at resolve (/Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/carbond/node_modules/bond/lib/bond.js:16:14)
    at /Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/carbond/node_modules/bond/lib/bond.js:102:12
    at module.exports.oo._genStaticDocs (/Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/carbond/lib/Service.js:48:21)
    at module.exports.oo._main.gen-static-docs (/Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/carbond/lib/Service.js:71:12)
    at Atom._invokeMain (/Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/atom/lib/atom.js:408:17)
    at /Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/atom/lib/atom.js:382:14
    at /Users/Matt/Documents/Development/public-status-api/node_modules/carbon-io/node_modules/atom/node_modules/@carbon-io/fibers/index.js:136:20

package.json:

{
  "name": "public-status-api",
  "description": "Carbon.io api to serve up data from public status events.",
  "dependencies": {
    "carbon-io": "[email protected]:carbon-io/carbon-io.git#v0.1.14",
    "pacemaker": "git+ssh://[email protected]:mongolab/pacemaker.git#v2.0.3"
  }
}

It works when tag 0.1.5 is used.

Creating an issue to discuss what examples we want to work on. We said previously that we want to make the React tutorials (Basic API + Auth) and a lot more examples which highlight specific features that we can link to from the docs.

Current examples (with principles they are demonstrating)

• Contacts: Full example showing MongoDB HTTP Basic Auth, environment variables, collections, collection ACL, and operation config. It contains an example of user management. For testing it shows HTTP testing, fixtures, and context.
• Hello World: Simple endpoint, HTTP testing.
• Hello World AAC: MongoDB API key authentication, HTTP testing, test setup.
• Hello World Chaining: Microservice chaining/proxying, HTTP testing.
• Hello World Parameter Parsing: Parameters and response definitions, HTTP testing.
• Hello World MongoDB: Modularized endpoints, MongoDB, HTTP Errors, sub-endpoints, path parameters, environment variables, HTTP testing, test setup.
• Zipcode: MongoDB Collection, HTTP testing, fixtures.
• Test Suites: Building test suites.
• Simple Cmdline App: CLI programs with Atom, command args.

Other examples

These are topics we could highlight with examples. They are either not covered or tangentially covered by the current examples. For example, Hello World MongoDB contains sub-endpoints, but it isn't the single focus of the example.

• MongoDB HTTP Basic Auth
• Custom Auth
• MongoDBCollection Config
• MongoDBCollection Hooks
• Collection ACL
• Logging
• How to document your API using md files for larger or formatted documentation.
• Environment variables
• Param schemas
• Collections
• HTTP errors
• Middleware
• Endpoint params
• Sub-endpoints
• Multiple DBs
• Limiters
• Using IdGenerators
• Re-using ACLs
• Using bond
• Structuring large services
• Custom API Key Auth
• Custom HTTP Basic Auth

Highlighting Test-Tube

I think it would be good to make examples to specifically highlight testing functionality. This would increase the discoverability and readability of example usage of test-tube. For example, even though many of our current examples include setup and teardown in their tests, having a specific example focusing on this would allow us to highlight it more clearly.

• Basic tests
• Setup and teardown
• Parent
• Context
• HTTP Tests

Suggestions

Please reply to this issue with suggestions for this list (whether you think we should add or remove items).

Edits:

I'd like for the closed/hover states to look like how it does now on docs.carbon.io. Instead of the ReadTheDocs logo, I'd like for it to say Carbon.io and "version: latest" to be aligned right.

On the Expanded view, I'd like for the bottom "Documentation hosted by RTD" to be removed (even though we love you guys!). I'd also like the bottom border for the "version:latest" on expanded view similar to how it is right now on docs.carbon.io.

Should we re-name Quick Start to Installation and Quick Start? In any case we need to add more installation details like required node versions, etc...