<commit_before>---
layout: default
title: Skydoc Deprecation
stylesheet: docs
---

## Why was Skydoc deprecated?

Skydoc functioned by evalutating Starlark files as if they were python. Unfortunately, while
Starlark is **similar** to Python, there are some important syntactic differences between
the languages. Assuming compatibility between the languages was inherently brittle, and resulted
in a maintenance burden on the Starlark code. Specifically, if one of your transitive dependencies
were to adopt a Starlark-compatible, python-incompatible construct, your Skydoc integration would
break!

Skydoc still exists as it's a nontrivial migration to Stardoc, but we plan on removing it
in mid 2019.

## How to migrate

Stardoc is not a drop-in replacement for Skydoc. Its usage is slightly different, and it has some
new features. It's recommended to take a look at the root Stardoc documentation, but here is
a brief summary of some things to note for migration:

### Docstring specification

Stardoc uses inline documentation strings instead of python-style docstrings.
For example, Skydoc documentation may have been specified with:

```
checkstyle = rule(
    implementation = _impl,
    attrs = {
        "srcs": attr.label_list(allow_files = FileType([".java"]),
        "deps": attr.label(),
    },
)
"""Example rule documentation.

Example:
  Here is an example of how to use this rule.

Args:
  srcs: Source files used to build this target.<commit_msg>fix site deprecation-notice rule comparison (#171)<commit_after>---
layout: default
title: Skydoc Deprecation
stylesheet: docs
---

## Why was Skydoc deprecated?

Skydoc functioned by evalutating Starlark files as if they were python. Unfortunately, while
Starlark is **similar** to Python, there are some important syntactic differences between
the languages. Assuming compatibility between the languages was inherently brittle, and resulted
in a maintenance burden on the Starlark code. Specifically, if one of your transitive dependencies
were to adopt a Starlark-compatible, python-incompatible construct, your Skydoc integration would
break!

Skydoc still exists as it's a nontrivial migration to Stardoc, but we plan on removing it
in mid 2019.

## How to migrate

Stardoc is not a drop-in replacement for Skydoc. Its usage is slightly different, and it has some
new features. It's recommended to take a look at the root Stardoc documentation, but here is
a brief summary of some things to note for migration:

### Docstring specification

Stardoc uses inline documentation strings instead of python-style docstrings.
For example, Skydoc documentation may have been specified with:

```
my_rule = rule(
    implementation = _my_rule_impl,
    attrs = {
        "srcs": attr.label_list(),
        "deps": attr.label_list(),
    },
)
"""Example rule documentation.

Example:
  Here is an example of how to use this rule.

Args:
  srcs: Source files used to build this target.
{'fraction_non_alphanumeric': 0.061501868841318384, 'fraction_numerical': 0.0037376826367652057, 'mean_word_length': 4.411764705882353, 'pattern_counts': {'":': 4, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2207567', 'n_tokens_mistral': 797, 'n_tokens_neox': 742, 'n_words': 391}