This repository contains the new Developer Center of CARTO carto.com/developers. The developer center is built on top of Jekyll, a simple content management system for static sites.
This repository is an orchestration repository. It does not host the totality of the content; the content specific to each component must be in the component's history.
Hi! Thanks or considering contributing to the Developer Center! Please choose one of the templates for new issues and let us know what we can do to improve our documentation. Feel free to browse current issues and join the discussion.
This section outlines the procedure to contribute to the CARTO Developer Center, the main hub of documentation for CARTO Engine developers. The Developer Center is the complement to the Developer Center, that focuses in helping CARTO user products.
The contributing use cases covered by this document include
- new content to the Developer Center
- small fixes to existing content
- ideas for new and improving existing content
- substantial changes or removal of existing content
That is, any CARTO employee can contribute to the Developer Center with suggestions and feedback but also with actual content. We want everyone to feel comfortable discussing and contributing Developer Center content to keep it relevant and updated, this has to be a whole company effort.
The Product Team at CARTO is the owner of the Developer Center content.
As mentioned before, the Product Team will act as coordinators of the content on the Developer Center, but that does not mean they will be the only contributors and they shouldn't!
The Developer Center is developed as a static website using Jekyll and hosted in this Github repository in very much the same way CARTO maintains other web applications like our main website, several blogs, and the Developer Center. This common practice help to maintain the same workflows and behaviors CARTO team is well versed and used to.
The content of the Developer Center is hosted on the CartoDB/Developers repository, and thanks to the awesome work of CARTO Product team the website is deployed with a number of features that help and boosts collaboration.
- Any merge to the
masterbranch of the git repository triggers the full deployment of the website without any human intervention. - Any Pull Request triggers the deployment of a staging version of the website. Given for example a branch named
fix-typo, when a contributor starts a PR, a new website athttps://fix-typo.developers.carto-staging.com/developers(REVIEW) is automatically generated in order to help the contributor and reviewers to inspect.
Given the technological context and common practices, the procedure to contribute to the Developer Center follows the same guidelines to other content repositories, that is, using Github issues and the Pull Request process.
Any user with feedback about the Developer Center is encouraged to follow these steps, differentiating three main scenarios:
-
If you want to contribute to something related to the Developer Center website (layout, new feature, etc.), start the discussion here, in this repository.
-
If you want to contribute to the
fundamentalssection, contents thar are transversal to any Engine component, start the discussion here, in this repository. -
If you want to contribute to any other content, start the discussion in the component's repository. You will always find the link to each component's repository in the component's microsite of the Developer Center.
- Search on the repository issue tracker for similar concerns and discussions and add him/herself to them to provide additional feedback or support to the fix.
- Create a new issue if there are no related conversations, using the appropriate template for:
- Small fix: typos, screenshots that need to be updated, broken links and so on. If the contributor is tech savvy, she can skip the issue creation and directly produce a Pull Request most of the times directly from Github interface.
- Content discussion: significant changes to existing content or the creation of new content that needs the interaction of several stakeholders: a new feature that needs to be added, a guide that needs to be reviewed because of a significant change in some component, etc.
- The contributor or a member of the Product will look for the appropriate repository to start the standard workflow in there, or if the content is related to the
fundamentalssections, create a new branch frommasterto implement the changes.- Only Product members are allowed to push changes to
masterbranch directly or merging approved Pull Requests. - If the PR comes from an issue, its identifier will be used as a prefix, otherwise the
fix-prefix will be used.
- Only Product members are allowed to push changes to
- The contributor will produce the modifications until a discussion point where a new Pull Request will be created. At that moment a staging version of the Developer Center will be deployed for everyone to review.
- With the PR a new discussion will start. The contributor can at that moment decide who are the most appropriate colleagues to summon for discussion or review. The
reviewfeature of Github is encouraged in order to make explicit the decisions and request for changes. - Once the content is agreed or immediately if this is just a simple fix, the contributor will tag the Github handle for the Developer Center managers
@CartoDB/dc-managers. A member of the group will add herself as a reviewer and perform the final approval or rejection of the Pull Request. - If the PR is approved, the member of the Developer Center managers group will execute the merge and branch removal.
git clone git@github.com:CartoDB/developers.git
cd developers
Execute docker-compose up. It will take between 5-10 minutes.
Install node dependencies (only once):
docker-compose run developers npm install
You can fetch that documentation by executing the following command:
docker-compose run developers grunt doc
Run the documentation locally:
docker-compose run developers grunt serve
Open a tab in your browser and go to http://EXTERNAL_ADDRESS:9000/developers/, it will track changes to rebuild and reload your browser so you can see your modifications.
To find the correct external address, keep an eye on the console. You will see something like this:
Running "browserSync:livereload" (browserSync) task
[Browsersync] Access URLs:
-----------------------------------
Local: http://localhost:9000
External: http://172.19.0.2:9000
Full API Reference of CARTO uses Grunt tasks for development. You'll need Ruby and a Node.js version >= 0.10.0 installed, as well as Bundler.
-
Install XCode Command Line Tools
-
Install Homebrew
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install) -
Install nodejs.org 0.10.x
brew install node -
Install ruby-install
brew install ruby-install -
Install Ruby
ruby-install ruby 2.3.0 -
Install bundler
gem install bundler -
Set Ruby version to 2.3.0
echo '2.3.0' > .ruby-version -
Install RubyGems dependencies which include Jekyll
bundle install -
Install Python
brew install python -
Install Python dependencies to generate the doc
pip install sphinx pip install sphinxcontrib-napoleon pip install geopandas
-
Install the Grunt CLI
npm install -g grunt-cli -
Install the Documentation Generator
npm install -g documentation -
Install npm dependencies
npm install -
Install Pandoc 2.1.2. Check the documentation
-
Install the pandoc filters
pip install pandocfilters
You can fetch that documentation by executing the following command:
grunt doc
Run the documentation locally:
grunt serve
A tab in your browser will open, go to http://localhost:9000/developers/, it will track changes to rebuild and reload your browser so you can see your modifications.