├── .dockerignore ├── .github ├── dependabot.yaml └── workflows │ ├── ci.yml │ └── stale.yml ├── .gitignore ├── .kick ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── Dockerfile ├── Gemfile ├── Gemfile.lock ├── HISTORY.md ├── LICENSE ├── README.md ├── Rakefile ├── bin └── github-markup ├── github-markup.gemspec ├── lib ├── github-markup.rb └── github │ ├── commands │ ├── pod2html │ ├── pod62html │ └── rest2html │ ├── markup.rb │ ├── markup │ ├── command_implementation.rb │ ├── gem_implementation.rb │ ├── implementation.rb │ ├── markdown.rb │ └── rdoc.rb │ └── markups.rb ├── script ├── bootstrap ├── bootstrap.contrib └── cibuild └── test ├── fixtures └── fail.sh ├── markup_test.rb └── markups ├── README.asciidoc ├── README.asciidoc.html ├── README.creole ├── README.creole.html ├── README.directives.rst ├── README.directives.rst.html ├── README.hidetitle.asciidoc ├── README.hidetitle.asciidoc.html ├── README.litcoffee ├── README.litcoffee.html ├── README.long.rst ├── README.long.rst.html ├── README.markdown ├── README.markdown.html ├── README.mediawiki ├── README.mediawiki.html ├── README.noformat ├── README.noformat.html ├── README.org ├── README.org.html ├── README.pod ├── README.pod.html ├── README.rdoc ├── README.rdoc.html ├── README.rst ├── README.rst.html ├── README.rst.txt ├── README.rst.txt.html ├── README.textile ├── README.textile.html ├── README.toc.asciidoc ├── README.toc.asciidoc.html ├── README.toc.rst ├── README.toc.rst.html ├── README.txt └── README.txt.html /.dockerignore: -------------------------------------------------------------------------------- 1 | Dockerfile 2 | -------------------------------------------------------------------------------- /.github/dependabot.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | version: 2 3 | updates: 4 | - package-ecosystem: 'bundler' 5 | directory: '/' 6 | schedule: 7 | interval: 'weekly' 8 | commit-message: 9 | prefix: 'chore(deps)' 10 | groups: 11 | dependencies: 12 | applies-to: version-updates 13 | update-types: 14 | - 'minor' 15 | - 'patch' 16 | - package-ecosystem: 'github-actions' 17 | directory: '/' 18 | schedule: 19 | interval: 'weekly' 20 | commit-message: 21 | prefix: 'chore(deps)' 22 | groups: 23 | dependencies: 24 | applies-to: version-updates 25 | update-types: 26 | - 'minor' 27 | - 'patch' 28 | - package-ecosystem: 'docker' 29 | directory: '/' 30 | schedule: 31 | interval: 'weekly' 32 | commit-message: 33 | prefix: 'chore(deps)' 34 | groups: 35 | dependencies: 36 | applies-to: version-updates 37 | update-types: 38 | - 'minor' 39 | - 'patch' 40 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | on: [push, pull_request] 3 | 4 | env: 5 | JRUBY_OPTS: -Xcext.enabled=true 6 | 7 | permissions: 8 | contents: read 9 | 10 | jobs: 11 | build: 12 | name: "Test / Ruby ${{ matrix.ruby }}" 13 | runs-on: ubuntu-latest 14 | strategy: 15 | matrix: 16 | ruby: 17 | - "3.1" 18 | - "3.2" 19 | - "3.3" 20 | - "3.4" 21 | fail-fast: false 22 | 23 | steps: 24 | - name: Checkout 25 | uses: actions/checkout@v4.2.2 26 | with: 27 | fetch-depth: 10 28 | 29 | - uses: ruby/setup-ruby@354a1ad156761f5ee2b7b13fa8e09943a5e8d252 # v1 30 | with: 31 | ruby-version: ${{ matrix.ruby }} 32 | bundler-cache: true 33 | 34 | - uses: actions/setup-python@v5.5.0 35 | with: 36 | # This should match lib/github/markups.rb GitHub::Markups::MARKUP_RST 37 | python-version: "3.x" 38 | 39 | - uses: actions/cache@v4.2.3 40 | with: 41 | path: ~/.cache/pip 42 | key: ${{ runner.os }}-pip 43 | 44 | - name: Install Perl dependencies 45 | run: | 46 | curl -1sLf \ 47 | 'https://dl.cloudsmith.io/public/nxadm-pkgs/rakudo-pkg/setup.deb.sh' \ 48 | | sudo -E bash 49 | sudo apt-get update -qq 50 | sudo apt-get install perl rakudo-pkg 51 | 52 | curl -L http://cpanmin.us | perl - --sudo App::cpanminus 53 | sudo cpanm --installdeps --notest Pod::Simple 54 | 55 | - name: Install Python dependencies 56 | run: python -m pip install docutils 57 | 58 | - name: Run rake 59 | run: | 60 | export PATH=$PATH:/.perl6/bin:/opt/rakudo-pkg/bin 61 | bundle exec rake 62 | -------------------------------------------------------------------------------- /.github/workflows/stale.yml: -------------------------------------------------------------------------------- 1 | name: Mark stale issues and pull requests 2 | 3 | on: 4 | schedule: 5 | - cron: "0 12 * * *" 6 | 7 | jobs: 8 | stale: 9 | runs-on: ubuntu-latest 10 | permissions: 11 | issues: write 12 | pull-requests: write 13 | 14 | steps: 15 | - uses: actions/stale@v9.1.0 16 | with: 17 | repo-token: ${{ secrets.GITHUB_TOKEN }} 18 | stale-issue-message: > 19 | This issue has been automatically marked as stale because it has not 20 | had recent activity. It will be closed if no further activity occurs. 21 | Thank you for your contributions. 22 | stale-pr-message: > 23 | This pull request has been automatically marked as stale because it has not 24 | had recent activity. It will be closed if no further activity occurs. 25 | Thank you for your contributions. 26 | exempt-issue-labels: keep 27 | exempt-pr-labels: keep 28 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.pyc 2 | pkg/ 3 | .bundle 4 | .project 5 | .buildpath 6 | *~ 7 | vendor/ 8 | .DS_Store 9 | .venv 10 | venv 11 | -------------------------------------------------------------------------------- /.kick: -------------------------------------------------------------------------------- 1 | # take control of the growl notifications 2 | module GrowlHacks 3 | def growl(type, subject, body, *args, &block) 4 | case type 5 | when Kicker::GROWL_NOTIFICATIONS[:succeeded] 6 | puts subject = "Success" 7 | body = body.split("\n").last 8 | when Kicker::GROWL_NOTIFICATIONS[:failed] 9 | subject = "Failure" 10 | puts body 11 | body = body.split("\n").last 12 | else 13 | return nil 14 | end 15 | super(type, subject, body, *args, &block) 16 | end 17 | end 18 | 19 | Kicker.send :extend, GrowlHacks 20 | 21 | # no logging 22 | Kicker::Utils.module_eval do 23 | def log(message) 24 | nil 25 | end 26 | end -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. 6 | 7 | ## Our Standards 8 | 9 | Examples of behavior that contributes to creating a positive environment include: 10 | 11 | * Using welcoming and inclusive language 12 | * Being respectful of differing viewpoints and experiences 13 | * Gracefully accepting constructive criticism 14 | * Focusing on what is best for the community 15 | * Showing empathy towards other community members 16 | 17 | Examples of unacceptable behavior by participants include: 18 | 19 | * The use of sexualized language or imagery and unwelcome sexual attention or advances 20 | * Trolling, insulting/derogatory comments, and personal or political attacks 21 | * Public or private harassment 22 | * Publishing others' private information, such as a physical or electronic address, without explicit permission 23 | * Other conduct which could reasonably be considered inappropriate in a professional setting 24 | 25 | ## Our Responsibilities 26 | 27 | Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. 28 | 29 | Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. 30 | 31 | ## Scope 32 | 33 | This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. 34 | 35 | ## Enforcement 36 | 37 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [opensource@github.com](mailto:opensource@github.com). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. 38 | 39 | Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. 40 | 41 | ## Attribution 42 | 43 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://contributor-covenant.org/version/1/4][version] 44 | 45 | [homepage]: https://contributor-covenant.org 46 | [version]: https://contributor-covenant.org/version/1/4/ 47 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE). 4 | 5 | This project adheres to a [Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code. 6 | 7 | [code-of-conduct]: CODE_OF_CONDUCT.md 8 | 9 | This library's only job is to decide which markup format to use and call out to an external library to convert the markup to HTML (see the [README](README.md) for more information on how markup is rendered on GitHub.com). 10 | 11 | If you are having an issue with: 12 | 13 | * **Syntax highlighting** - see [github/linguist](https://github.com/github/linguist/blob/master/CONTRIBUTING.md#fixing-syntax-highlighting) 14 | * **Markdown on GitHub** - contact [GitHub Support](https://support.github.com/) 15 | * **Styling issues on GitHub** - see [primer-markdown](https://github.com/primer/primer-css/tree/master/modules/primer-markdown) module in the [primer/primer-css](https://github.com/primer/primer-css) repository 16 | 17 | Anything else - [search open issues](https://github.com/github/markup/issues) or create an issue and and we'll help point you in the right direction. 18 | 19 | ## Submitting a Pull Request 20 | 21 | 1. Fork it. 22 | 2. Create a branch (`git checkout -b my_markup`) 23 | 3. Commit your changes (`git commit -am "Added Snarkdown"`) 24 | 4. Push to the branch (`git push origin my_markup`) 25 | 5. Open a [Pull Request][1] 26 | 6. Enjoy a refreshing Diet Coke and wait 27 | 28 | **dependencies** 29 | 30 | You can run `script/bootstrap.contrib` to fetch them all. 31 | 32 | ## Testing 33 | 34 | To run the tests: 35 | 36 | $ rake 37 | 38 | If nothing complains, congratulations! 39 | 40 | ## Releasing a new version 41 | 42 | If you are the current maintainer of this gem: 43 | 44 | 0. Bump the version number in `lib/github-markup.rb`, adhering to [Semantic Versioning](http://semver.org/) 45 | 0. Update `HISTORY.md` 46 | 0. Test the latest version on GitHub 47 | 0. Build the new version with `rake build` 48 | 0. Copy `pkg/github-markup*.gem` to `vendor/cache` in your local checkout of GitHub 49 | 0. Update the version for `github-markup` in the `Gemfile` 50 | 0. Run `bundle update --local github-markup` 51 | 0. Run any relevant tests and test it manually from the browser. 52 | 0. Push the new gem release with `rake release`. If you don't have permission to release to rubygems.org, contact one of the existing owners (`gem owners github-markup`) and ask them to add you. 53 | 54 | [1]: http://github.com/github/markup/pulls 55 | [r2h]: lib/github/commands/rest2html 56 | [r2hc]: lib/github/markups.rb#L51 57 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM ubuntu:trusty 2 | 3 | RUN apt-get update -qq 4 | RUN apt-get install -y apt-transport-https 5 | 6 | RUN apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 379CE192D401AB61 7 | RUN echo "deb https://dl.bintray.com/nxadm/rakudo-pkg-debs `lsb_release -cs` main" | tee -a /etc/apt/sources.list.d/rakudo-pkg.list 8 | RUN apt-get update -qq 9 | 10 | RUN apt-get install -y \ 11 | perl rakudo-pkg curl git build-essential python python-pip \ 12 | libssl-dev libreadline-dev zlib1g-dev \ 13 | libicu-dev cmake pkg-config 14 | 15 | ENV PATH $PATH:/opt/rakudo-pkg/bin 16 | RUN install-zef-as-user && zef install Pod::To::HTML 17 | 18 | RUN curl -L http://cpanmin.us | perl - App::cpanminus 19 | RUN cpanm --installdeps --notest Pod::Simple 20 | 21 | RUN pip install docutils 22 | 23 | ENV PATH $PATH:/root/.rbenv/bin:/root/.rbenv/shims 24 | RUN curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-installer | bash 25 | RUN rbenv install 2.4.1 26 | RUN rbenv global 2.4.1 27 | RUN rbenv rehash 28 | 29 | RUN gem install bundler 30 | 31 | WORKDIR /data/github-markup 32 | COPY github-markup.gemspec . 33 | COPY Gemfile . 34 | COPY Gemfile.lock . 35 | COPY lib/github-markup.rb lib/github-markup.rb 36 | RUN bundle 37 | 38 | ENV LC_ALL en_US.UTF-8 39 | RUN locale-gen en_US.UTF-8 40 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source "https://rubygems.org" 2 | gemspec 3 | 4 | gem "redcarpet", :platforms => :ruby 5 | gem "kramdown", :platforms => :jruby 6 | gem "RedCloth" 7 | # using a tag version here because 0.18.3 was not published by the author to encourage users to upgrade. 8 | # however we want to bump up to this version since this has a security patch 9 | gem "commonmarker", git: "https://github.com/gjtorikian/commonmarker.git", tag: "v0.18.3" 10 | gem "rdoc", "~> 6.13.1" 11 | gem "org-ruby", "0.9.12" 12 | gem "creole", "~>0.5.0" 13 | gem "wikicloth", "=0.8.3" 14 | gem "twitter-text", "~> 1.14" 15 | gem "asciidoctor", "~> 2.0.5" 16 | gem "rake" 17 | gem "rexml" 18 | gem "nokogiri", "~> 1.18.4" 19 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GIT 2 | remote: https://github.com/gjtorikian/commonmarker.git 3 | revision: 2838ebaa83ee0081d481c21f3bc0e4cb3e8de9da 4 | tag: v0.18.3 5 | specs: 6 | commonmarker (0.18.3) 7 | ruby-enum (~> 0.5) 8 | 9 | PATH 10 | remote: . 11 | specs: 12 | github-markup (5.0.1) 13 | 14 | GEM 15 | remote: https://rubygems.org/ 16 | specs: 17 | RedCloth (4.3.4) 18 | activesupport (7.1.5.1) 19 | base64 20 | benchmark (>= 0.3) 21 | bigdecimal 22 | concurrent-ruby (~> 1.0, >= 1.0.2) 23 | connection_pool (>= 2.2.5) 24 | drb 25 | i18n (>= 1.6, < 2) 26 | logger (>= 1.4.2) 27 | minitest (>= 5.1) 28 | mutex_m 29 | securerandom (>= 0.3) 30 | tzinfo (~> 2.0) 31 | asciidoctor (2.0.23) 32 | base64 (0.2.0) 33 | benchmark (0.4.0) 34 | bigdecimal (3.1.9) 35 | builder (3.3.0) 36 | cgi (0.4.2) 37 | charlock_holmes (0.7.9) 38 | concurrent-ruby (1.3.5) 39 | connection_pool (2.5.0) 40 | crass (1.0.6) 41 | creole (0.5.0) 42 | date (3.4.1) 43 | drb (2.2.1) 44 | expression_parser (0.9.0) 45 | github-linguist (9.1.0) 46 | cgi 47 | charlock_holmes (~> 0.7.7) 48 | mini_mime (~> 1.0) 49 | rugged (~> 1.0) 50 | html-pipeline (1.11.0) 51 | activesupport (>= 2) 52 | nokogiri (~> 1.4) 53 | htmlentities (4.3.4) 54 | i18n (1.14.7) 55 | concurrent-ruby (~> 1.0) 56 | logger (1.7.0) 57 | mini_mime (1.1.5) 58 | mini_portile2 (2.8.8) 59 | minitest (5.25.5) 60 | mutex_m (0.3.0) 61 | nokogiri (1.18.7) 62 | mini_portile2 (~> 2.8.2) 63 | racc (~> 1.4) 64 | nokogiri (1.18.7-aarch64-linux-gnu) 65 | racc (~> 1.4) 66 | nokogiri (1.18.7-arm-linux-gnu) 67 | racc (~> 1.4) 68 | nokogiri (1.18.7-arm64-darwin) 69 | racc (~> 1.4) 70 | nokogiri (1.18.7-x86_64-darwin) 71 | racc (~> 1.4) 72 | nokogiri (1.18.7-x86_64-linux-gnu) 73 | racc (~> 1.4) 74 | nokogiri-diff (0.3.0) 75 | nokogiri (~> 1.5) 76 | tdiff (~> 0.4) 77 | org-ruby (0.9.12) 78 | rubypants (~> 0.2) 79 | psych (5.2.3) 80 | date 81 | stringio 82 | racc (1.8.1) 83 | rake (13.2.1) 84 | rdoc (6.13.1) 85 | psych (>= 4.0.0) 86 | redcarpet (3.6.1) 87 | rexml (3.4.1) 88 | ruby-enum (0.9.0) 89 | i18n 90 | rubypants (0.7.1) 91 | rugged (1.9.0) 92 | sanitize (6.1.3) 93 | crass (~> 1.0.2) 94 | nokogiri (>= 1.12.0) 95 | securerandom (0.3.2) 96 | stringio (3.1.6) 97 | tdiff (0.4.0) 98 | twitter-text (1.14.7) 99 | unf (~> 0.1.0) 100 | tzinfo (2.0.6) 101 | concurrent-ruby (~> 1.0) 102 | unf (0.1.4) 103 | unf_ext 104 | unf_ext (0.0.9.1) 105 | wikicloth (0.8.3) 106 | builder 107 | expression_parser 108 | htmlentities 109 | nokogiri 110 | twitter-text 111 | 112 | PLATFORMS 113 | aarch64-linux 114 | arm-linux 115 | arm64-darwin 116 | x86-linux 117 | x86_64-darwin 118 | x86_64-linux 119 | 120 | DEPENDENCIES 121 | RedCloth 122 | activesupport (~> 7.1.5) 123 | asciidoctor (~> 2.0.5) 124 | commonmarker! 125 | creole (~> 0.5.0) 126 | github-linguist (>= 7.1.3) 127 | github-markup! 128 | html-pipeline (~> 1.0) 129 | kramdown 130 | minitest (~> 5.4, >= 5.4.3) 131 | nokogiri (~> 1.18.4) 132 | nokogiri-diff (~> 0.3.0) 133 | org-ruby (= 0.9.12) 134 | rake 135 | rdoc (~> 6.13.1) 136 | redcarpet 137 | rexml 138 | sanitize (>= 4.6.3) 139 | twitter-text (~> 1.14) 140 | wikicloth (= 0.8.3) 141 | 142 | BUNDLED WITH 143 | 2.5.9 144 | -------------------------------------------------------------------------------- /HISTORY.md: -------------------------------------------------------------------------------- 1 | ## 5.0.1 - 2024-06-17 2 | * Bump activesupport from 4.0 to 7.1.3.4 3 | 4 | ## 5.0.0 - 2024-06-17 5 | * Drop support for Ruby versions < 3 6 | * Bump nokogiri from 1.8.1 to 1.16.5 7 | * Bump nokogiri-diff from 0.2.0 to 0.3.0 8 | * Bump rdoc from 3.6 to 6.7.0 9 | * Update CommandImplementation to better support large files (affecting RST and POD6 rendering) 10 | 11 | ## 4.0.2 - 2023-10-10 12 | * Add support for .mdx files in markdown 13 | 14 | ## 4.0.1 - 2022-03-07 15 | * Update to commonmarker 0.18.3; There isn't a version on RubyGems for this, so this is pointing to a [tag version on GitHub](https://github.com/gjtorikian/commonmarker/blob/v0.18.3/commonmarker.gemspec) 16 | 17 | ## 4.0.0 - 2021-03-31 18 | 19 | * Drop support for Python 2 in RST rendering [#1456](https://github.com/github/markup/pull/1456) 20 | 21 | ## 3.0.5 - 2020-11-12 22 | 23 | * Add commonmarker_exts to commonmarker options [#1268](https://github.com/github/markup/pull/1268) 24 | * Check whether filename is set when rendering Asciidoc. [#1290](https://github.com/github/markup/pull/1290) 25 | 26 | ## 3.0.4 - 2019-04-03 27 | 28 | * Expose options in #render_s [#1249](https://github.com/github/markup/pull/1249) 29 | * Upgrade to Asciidoctor 2.0.x [#1264](https://github.com/github/markup/pull/1264) 30 | 31 | ## 3.0.3 - 2018-12-17 32 | 33 | * Temporarily remove support for POD6 [#1248](https://github.com/github/markup/pull/1248) 34 | 35 | ## 3.0.2 - 2018-12-12 36 | 37 | * Add support for POD6 [#1173](https://github.com/github/markup/pull/1173) 38 | 39 | ## 3.0.1 - 2018-10-19 40 | 41 | * Remove linguist-detected RMarkdown files from the Markdown renderer [#1237](https://github.com/github/markup/pull/1237) 42 | 43 | ## 3.0.0 - 2018-10-18 44 | 45 | * Allow passing options through to CommonMarker [#1236](https://github.com/github/markup/pull/1236) 46 | * Symlink option is now a keyword arg [#1236](https://github.com/github/markup/pull/1236) 47 | 48 | ## 2.0.2 - 2018-10-15 49 | 50 | * Don't render rmd files as Markdown [#1235](https://github.com/github/markup/pull/1235) 51 | 52 | ## 2.0.1 - 2018-06-29 53 | 54 | * Create anchor for every =item directive in POD files [#1165](https://github.com/github/markup/pull/1165) 55 | 56 | ## 2.0.0 - 2018-01-31 57 | 58 | * Remove filesystem access [#1157](https://github.com/github/markup/pull/1157) 59 | 60 | ## 1.7.0 - 2018-01-30 61 | 62 | ### Changed 63 | 64 | * Updates for Linguist v6 [#1139](https://github.com/github/markup/pull/1139) 65 | * Update to Nokogiri ~> 1.8; drop support for Ruby 2.0 [#1156](https://github.com/github/markup/pull/1156) 66 | 67 | ## 1.6.2 - 2017-11-27 68 | 69 | ### Changed 70 | 71 | * Only report basename in usage [#1131](https://github.com/github/markup/pull/1131) 72 | * rest2html parameter signature fix [#1082](https://github.com/github/markup/pull/1082) 73 | 74 | ## 1.6.1 - 2017-07-25 75 | 76 | ### Changed 77 | 78 | * Added support for highlight directive in rST [#925](https://github.com/github/markup/pull/925) 79 | * Fixes to documentation and code style [#1009](https://github.com/github/markup/pull/1009) [#1071](https://github.com/github/markup/pull/1071) [#1087](https://github.com/github/markup/pull/1087) 80 | * Test against newer Ruby versions [#1086](https://github.com/github/markup/pull/1086) 81 | * Upgrade to Asciidoctor 1.5.6.1 [#1088](https://github.com/github/markup/pull/1088) 82 | 83 | ## 1.6.0 - 2017-04-03 84 | 85 | ### Changed 86 | 87 | * Added filename argument to all renderers for additional context 88 | * Removed superfluous `rinku` dependency [#1035](https://github.com/github/markup/pull/1035) 89 | * Enable source-to-source navigation for `.adoc` AsciiDoc files, plus additional attributes passed through [#1039](https://github.com/github/markup/pull/1039) and [#1041](https://github.com/github/markup/pull/1041) 90 | 91 | ## 1.5.0 - 2017-03-27 92 | 93 | ### Added 94 | 95 | * Re-introduce [#537](https://github.com/github/markup/pull/537) to detect language of markup document 96 | However `github-linguist` is optional and this gem will fallback to extensions for detection. 97 | 98 | [Full changelog](https://github.com/github/markup/compare/v1.4.9...v1.5.0) 99 | 100 | ## 1.4.9 - 2017-03-27 101 | 102 | ### Changed 103 | 104 | * Reverted [#537](https://github.com/github/markup/pull/537) to avoid extra dependencies 105 | 106 | [Full changelog](https://github.com/github/markup/compare/v1.4.8...v1.4.9) 107 | 108 | ## 1.3.3 (2015-02-17) 109 | 110 | * Address a slight typo with `POSIX` [#456](https://github.com/github/markup/pull/456) 111 | 112 | [Full changelog](https://github.com/github/markup/compare/v1.3.2...v1.3.3) 113 | 114 | ## 1.3.2 (2015-02-17) 115 | 116 | * RST: Output code instead of tt for inline literals [#370](https://github.com/github/markup/pull/370) 117 | * RST: Add IDs to headers so that `.. contents` works with `.. sectnum` [#391](https://github.com/github/markup/pull/391) 118 | 119 | [Full changelog](https://github.com/github/markup/compare/v1.3.1...v1.3.2) 120 | 121 | ## 1.3.1 (2014-11-13) 122 | 123 | * Fix name error when trying to use newer versions of RedCarpet [#387](https://github.com/github/markup/pull/387) 124 | 125 | [Full changelog](https://github.com/github/markup/compare/v1.3.0...v1.3.1) 126 | 127 | ## 1.3.0 (2014-09-11) 128 | 129 | * Extend the field limit for tables to 50 characters for RST [#306](https://github.com/github/markup/pull/306) 130 | * Add `.mkdn` as a supported markdown extension [#308](https://github.com/github/markup/pull/308) 131 | * Upgrade wikicloth to 0.8.1 [#317](https://github.com/github/markup/pull/317) 132 | * Force encoding of posix-spawn output [#338](https://github.com/github/markup/pull/338) 133 | * Add `.rmd` as a supported markdown extension [#343](https://github.com/github/markup/pull/343) 134 | 135 | [Full changelog](https://github.com/github/markup/compare/v1.2.1...v1.3.0) 136 | 137 | ## 1.2.1 (2014-04-23) 138 | 139 | * Disable RST warnings [#290](https://github.com/github/markup/pull/290) 140 | 141 | [Full changelog](https://github.com/github/markup/compare/v1.2.0...v1.2.1) 142 | 143 | ## 1.1.1 (2014-04-03) 144 | 145 | * Upgrade to org-ruby 0.9.1 146 | * Set default encoding to UTF-8 for Python 2 147 | 148 | ## 1.1.0 (2014-03-10) 149 | 150 | * Raise GitHub::Markup::CommandError if external command exits with a non-zero status. 151 | * Remove support for literate Haskell (see #266) 152 | 153 | ## 0.5.1 (2010-09-30) 154 | 155 | * Support relative path links in rdoc 156 | 157 | ## 0.5.0 (2010-07-07) 158 | 159 | * Added creole support 160 | 161 | ## 0.4.0 (2010-04-23) 162 | 163 | * Removed man page support until it's ready. 164 | 165 | ## 0.3.3 (2010-03-29) 166 | 167 | * UTF-8 works with ReST now. 168 | 169 | ## 0.3.2 (2010-03-25) 170 | 171 | * Improved test runner 172 | * Forgive ReST problems that aren't user errors. 173 | 174 | ## 0.3.1 (2010-03-22) 175 | 176 | * Add .rst.txt extension 177 | * Fix ASCII encoding error while using print u'\u010c' non-ASCII char and similar. 178 | 179 | ## 0.3.0 (2010-03-11) 180 | 181 | * man rendering 182 | * `github-markup` command line runner 183 | 184 | ## 0.2.2 (2010-02-09) 185 | 186 | * pod fixes from Ricardo Signes 187 | 188 | ## 0.2.1 (2010-01-25) 189 | 190 | * ReST fixes from Michael Jones 191 | 192 | ## 0.2.0 (2010-01-10) 193 | 194 | * org-mode support 195 | 196 | ## 0.1.7 (2009-11-17) 197 | 198 | * Ditch asciidoc2html, call asciidoc directly 199 | 200 | ## 0.1.6 (2009-11-17) 201 | 202 | * mdown 203 | 204 | ## 0.1.5 (2009-11-17) 205 | 206 | * Actually, if we can't render a thing then don't. Not once, not never. 207 | 208 | ## 0.1.4 (2009-11-17) 209 | 210 | * Bugfix: Missing commands return the input (instead of nothing) 211 | 212 | ## 0.1.3 (2009-11-02) 213 | 214 | * Strip the INDEX comments from POD 215 | 216 | ## 0.1.2 (2009-11-02) 217 | 218 | * Renamed to `github-markup` 219 | * Bugfix: POD rendering works now, not just index 220 | 221 | ## 0.1.1 (2009-11-02) 222 | 223 | * Added `GitHub::Markup.can_render?` helper. 224 | * Bugfix: Actually check file extensions 225 | 226 | ## 0.1.0 (2009-11-02) 227 | 228 | * First release 229 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2009 GitHub 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining 4 | a copy of this software and associated documentation files (the 5 | "Software"), to deal in the Software without restriction, including 6 | without limitation the rights to use, copy, modify, merge, publish, 7 | distribute, sublicense, and/or sell copies of the Software, and to 8 | permit persons to whom the Software is furnished to do so, subject to 9 | the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be 12 | included in all copies or substantial portions of the Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 15 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 16 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 17 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 18 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 19 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 20 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | GitHub Markup 2 | ============= 3 | 4 | This library is the **first step** of a journey that every markup file in a repository goes on before it is rendered on GitHub.com: 5 | 6 | 1. `github-markup` selects an _underlying library_ to convert the raw markup to HTML. See the list of [supported markup formats](#markups) below. 7 | 1. The HTML is sanitized, aggressively removing things that could harm you and your kin—such as `script` tags, inline-styles, and `class` or `id` attributes. 8 | 1. Syntax highlighting is performed on code blocks. See [github/linguist](https://github.com/github/linguist#syntax-highlighting) for more information about syntax highlighting. 9 | 1. The HTML is passed through other filters that add special sauce, such as emoji, task lists, named anchors, CDN caching for images, and autolinking. 10 | 1. The resulting HTML is rendered on GitHub.com. 11 | 12 | Please note that **only the first step** is covered by this gem — the rest happens on GitHub.com. In particular, `markup` itself does no sanitization of the resulting HTML, as it expects that to be covered by whatever pipeline is consuming the HTML. 13 | 14 | Please see our [contributing guidelines](CONTRIBUTING.md) before reporting an issue. 15 | 16 | Markups 17 | ------- 18 | 19 | The following markups are supported. The dependencies listed are required if 20 | you wish to run the library. You can also run `script/bootstrap` to fetch them all. 21 | 22 | * [.markdown, .mdown, .mkdn, .md](http://daringfireball.net/projects/markdown/) -- `gem install commonmarker` (https://github.com/gjtorikian/commonmarker) 23 | * [.textile](https://textile-lang.com/) -- `gem install RedCloth` (https://github.com/jgarber/redcloth) 24 | * [.rdoc](https://ruby.github.io/rdoc/) -- `gem install rdoc -v 3.6.1` 25 | * [.org](http://orgmode.org/) -- `gem install org-ruby` (https://github.com/wallyqs/org-ruby) 26 | * [.creole](http://wikicreole.org/) -- `gem install creole` (https://github.com/larsch/creole) 27 | * [.mediawiki, .wiki](http://www.mediawiki.org/wiki/Help:Formatting) -- `gem install wikicloth` (https://github.com/nricciar/wikicloth) 28 | * [.rst](http://docutils.sourceforge.net/rst.html) -- `pip install docutils` 29 | * [.asciidoc, .adoc, .asc](http://asciidoc.org/) -- `gem install asciidoctor` (http://asciidoctor.org) 30 | * [.pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::XHTML` 31 | comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN. 32 | 33 | Installation 34 | ----------- 35 | 36 | ``` 37 | gem install github-markup 38 | ``` 39 | 40 | or 41 | 42 | ``` 43 | bundle install 44 | ``` 45 | 46 | from this directory. 47 | 48 | Usage 49 | ----- 50 | 51 | Basic form: 52 | 53 | ```ruby 54 | require 'github/markup' 55 | 56 | GitHub::Markup.render('README.markdown', "* One\n* Two") 57 | ``` 58 | 59 | More realistic form: 60 | 61 | ```ruby 62 | require 'github/markup' 63 | 64 | GitHub::Markup.render(file, File.read(file)) 65 | ``` 66 | 67 | And a convenience form: 68 | 69 | ```ruby 70 | require 'github/markup' 71 | 72 | GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "* One\n* Two") 73 | ``` 74 | 75 | Local Development 76 | ----------------- 77 | 78 | ```sh 79 | python3 -m venv .venv 80 | source .venv/bin/activate 81 | cd script 82 | ./bootstrap 83 | ``` 84 | 85 | Contributing 86 | ------------ 87 | 88 | See [Contributing](CONTRIBUTING.md). 89 | -------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env rake 2 | 3 | require "bundler/gem_tasks" 4 | 5 | require 'rake/testtask' 6 | Rake::TestTask.new(:test) do |test| 7 | test.libs << 'lib' << 'test' 8 | test.pattern = 'test/**/*_test.rb' 9 | test.verbose = true 10 | end 11 | 12 | desc "Open an irb session preloaded with this library" 13 | task :console do 14 | sh "irb -I lib -r bundler/setup -r github/markup" 15 | end 16 | 17 | task :default => :test 18 | -------------------------------------------------------------------------------- /bin/github-markup: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | 3 | $LOAD_PATH.unshift File.dirname(File.realpath(__FILE__)) + "/../lib" 4 | require 'github/markup' 5 | 6 | if ARGV.size < 1 7 | print "usage: #{File.basename($0)} FILE [ FILES ... ]\n" 8 | exit 1 9 | end 10 | 11 | sources = [] 12 | 13 | ARGV.each { |s| 14 | begin 15 | file = File.open( s, "r" ) 16 | sources.push [ s, file ] 17 | rescue Exception => e 18 | $stderr.print "error: #{e.message}\n" 19 | exit 1 20 | ensure 21 | end 22 | } 23 | 24 | sources.each { |name, file| 25 | print GitHub::Markup.render( name, file.read ) 26 | file.close 27 | } 28 | 29 | -------------------------------------------------------------------------------- /github-markup.gemspec: -------------------------------------------------------------------------------- 1 | require File.expand_path("../lib/github-markup", __FILE__) 2 | 3 | Gem::Specification.new do |s| 4 | s.name = "github-markup" 5 | s.version = GitHub::Markup::VERSION 6 | s.summary = "The code GitHub uses to render README.markup" 7 | s.description = <<~DESC 8 | This gem is used by GitHub to render any fancy markup such as Markdown, 9 | Textile, Org-Mode, etc. Fork it and add your own! 10 | DESC 11 | s.authors = ["Chris Wanstrath"] 12 | s.email = "chris@ozmm.org" 13 | s.homepage = "https://github.com/github/markup" 14 | s.license = "MIT" 15 | 16 | s.required_ruby_version = '>= 3.1.0' 17 | 18 | s.files = `git ls-files`.split($\) 19 | s.executables = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) } 20 | s.test_files = s.files.grep(%r{^(test|spec|features)/}) 21 | s.require_paths = %w[lib] 22 | 23 | s.add_development_dependency 'rake', '~> 12' 24 | s.add_development_dependency 'activesupport', '~> 7.1.5' 25 | s.add_development_dependency 'minitest', '~> 5.4', '>= 5.4.3' 26 | s.add_development_dependency 'html-pipeline', '~> 1.0' 27 | s.add_development_dependency 'sanitize', '>= 4.6.3' 28 | s.add_development_dependency 'nokogiri', '~> 1.18.4' 29 | s.add_development_dependency 'nokogiri-diff', '~> 0.3.0' 30 | s.add_development_dependency "github-linguist", ">= 7.1.3" 31 | end 32 | -------------------------------------------------------------------------------- /lib/github-markup.rb: -------------------------------------------------------------------------------- 1 | module GitHub 2 | module Markup 3 | VERSION = '5.0.1' 4 | Version = VERSION 5 | end 6 | end 7 | -------------------------------------------------------------------------------- /lib/github/commands/pod2html: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env perl 2 | 3 | use strict; 4 | use Pod::Simple::XHTML 3.11; 5 | 6 | my $p = Pod::Simple::XHTML->new; 7 | $p->html_header(''); 8 | $p->html_footer(''); 9 | $p->perldoc_url_prefix('https://metacpan.org/pod/'); 10 | $p->anchor_items(1); 11 | $p->strip_verbatim_indent(sub { 12 | my $lines = shift; 13 | (my $indent = $lines->[0]) =~ s/\S.*//; 14 | return $indent; 15 | }); 16 | $p->parse_from_file(shift); 17 | -------------------------------------------------------------------------------- /lib/github/commands/pod62html: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env perl6 2 | 3 | use v6; 4 | 5 | slurp.put; 6 | -------------------------------------------------------------------------------- /lib/github/commands/rest2html: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | """ 3 | rest2html - A small wrapper file for parsing ReST files at GitHub. 4 | 5 | Written in 2008 by Jannis Leidel 6 | 7 | Brandon Keepers 8 | Bryan Veloso 9 | Chris Wanstrath 10 | Dave Abrahams 11 | Garen Torikian 12 | Gasper Zejn 13 | Michael Jones 14 | Sam Whited 15 | Tyler Chung 16 | Vicent Marti 17 | 18 | To the extent possible under law, the author(s) have dedicated all copyright 19 | and related and neighboring rights to this software to the public domain 20 | worldwide. This software is distributed without any warranty. 21 | 22 | You should have received a copy of the CC0 Public Domain Dedication along with 23 | this software. If not, see . 24 | """ 25 | 26 | __author__ = "Jannis Leidel" 27 | __license__ = "CC0" 28 | __version__ = "0.1" 29 | 30 | import sys 31 | import os 32 | 33 | # This fixes docutils failing with unicode parameters to CSV-Table. The -S 34 | # switch and the following 3 lines can be removed after upgrading to python 3. 35 | if sys.version_info[0] < 3: 36 | reload(sys) 37 | sys.setdefaultencoding('utf-8') 38 | 39 | import site 40 | 41 | try: 42 | import locale 43 | locale.setlocale(locale.LC_ALL, '') 44 | except: 45 | pass 46 | 47 | import codecs 48 | import io 49 | 50 | from docutils import nodes, utils 51 | from docutils.parsers.rst import directives, roles 52 | from docutils.parsers.rst.directives.body import CodeBlock, Directive 53 | from docutils.core import publish_parts 54 | from docutils.writers.html4css1 import Writer, HTMLTranslator 55 | from docutils.parsers.rst.states import Body 56 | from docutils import nodes 57 | 58 | # By default, docutils provides two choices for unknown directives: 59 | # - Show errors if the reporting level is high enough 60 | # - Silently do not display them otherwise 61 | # Comments are not displayed, either. 62 | 63 | # This code monkey-patches docutils to show preformatted lines 64 | # in both these cases. 65 | 66 | # Recommended practice for repositories with rst files: 67 | # - If github is the preferred viewer for the rst files (e.g. README.rst), 68 | # then design the files to properly display for github. E.g., do not 69 | # include unknown directives or restructuredText comments. 70 | # - If github is NOT the preferred viewer for the rst files (e.g. 71 | # the files are designed to be used with sphinx extensions at readthedocs) 72 | # then include a restructuredText comment at the top of the file 73 | # explaining that the document will display much more nicely with its 74 | # preferred viewer, e.g. at readthedocs. 75 | 76 | original_behavior = False # Documents original docutils behavior 77 | github_display = True 78 | 79 | def extract_extension_options(field_list, option_spec): 80 | """ 81 | Overrides `utils.extract_extension_options` and inlines 82 | `utils.assemble_option_dict` to make it ignore unknown options passed to 83 | directives (i.e. ``:caption:`` for ``.. code-block:``). 84 | """ 85 | 86 | dropped = set() 87 | options = {} 88 | for name, value in utils.extract_options(field_list): 89 | convertor = option_spec.get(name) 90 | if name in options or name in dropped: 91 | raise utils.DuplicateOptionError('duplicate option "%s"' % name) 92 | 93 | # silently drop unknown options as long as they are not duplicates 94 | if convertor is None: 95 | dropped.add(name) 96 | continue 97 | 98 | # continue as before 99 | try: 100 | options[name] = convertor(value) 101 | except (ValueError, TypeError) as detail: 102 | raise detail.__class__('(option: "%s"; value: %r)\n%s' 103 | % (name, value, ' '.join(detail.args))) 104 | return options 105 | 106 | utils.extract_extension_options = extract_extension_options 107 | 108 | def unknown_directive(self, type_name): 109 | lineno = self.state_machine.abs_line_number() 110 | indented, indent, offset, blank_finish = \ 111 | self.state_machine.get_first_known_indented(0, strip_indent=False) 112 | text = '\n'.join(indented) 113 | if original_behavior: 114 | error = self.reporter.error( 115 | 'Unknown directive type "%s".' % type_name, 116 | nodes.literal_block(text, text), line=lineno) 117 | return [error], blank_finish 118 | elif github_display: 119 | cls = ['unknown_directive'] 120 | result = [nodes.literal_block(text, text, classes=cls)] 121 | return result, blank_finish 122 | else: 123 | return [nodes.comment(text, text)], blank_finish 124 | 125 | def comment(self, match): 126 | if not match.string[match.end():].strip() \ 127 | and self.state_machine.is_next_line_blank(): # an empty comment? 128 | return [nodes.comment()], 1 # "A tiny but practical wart." 129 | indented, indent, offset, blank_finish = \ 130 | self.state_machine.get_first_known_indented(match.end()) 131 | while indented and not indented[-1].strip(): 132 | indented.trim_end() 133 | if not original_behavior: 134 | firstline = ''.join(indented[:1]).split() 135 | if ' '.join(firstline[:2]) == 'github display': 136 | if len(firstline) == 3 and firstline[2] in ('on', 'off'): 137 | global github_display 138 | github_display = firstline[2] == 'on' 139 | if len(indented) == 1: 140 | return [nodes.comment()], 1 141 | text = '\n'.join(indented[1:]) 142 | cls = ['github_comment'] 143 | result = [nodes.literal_block(text, text, classes=cls)] 144 | return result, blank_finish 145 | text = '\n'.join(indented) 146 | return [nodes.comment(text, text)], blank_finish 147 | 148 | Body.comment = comment 149 | Body.unknown_directive = unknown_directive 150 | 151 | 152 | SETTINGS = { 153 | 'cloak_email_addresses': False, 154 | 'file_insertion_enabled': False, 155 | 'raw_enabled': True, 156 | 'strip_comments': True, 157 | 'doctitle_xform': True, 158 | 'initial_header_level': 2, 159 | 'report_level': 5, 160 | 'syntax_highlight': 'none', 161 | 'math_output': 'latex', 162 | 'field_name_limit': 50, 163 | } 164 | 165 | default_highlight_language = None 166 | 167 | class HighlightDirective(Directive): 168 | required_arguments = 1 169 | optional_arguments = 1 170 | option_spec = {} 171 | def run(self): 172 | """Track the default syntax highlighting language 173 | """ 174 | global default_highlight_language 175 | default_highlight_language = self.arguments[0] 176 | return [] 177 | 178 | class DoctestDirective(CodeBlock): 179 | """Render Sphinx 'doctest:: [group]' blocks as 'code:: python' 180 | """ 181 | 182 | def run(self): 183 | """Discard any doctest group argument, render contents as python code 184 | """ 185 | self.arguments = ['python'] 186 | return super(DoctestDirective, self).run() 187 | 188 | 189 | class GitHubHTMLTranslator(HTMLTranslator): 190 | 191 | # removes the
tag wrapped around docs 192 | # see also: http://bit.ly/1exfq2h (warning! sourceforge link.) 193 | def depart_document(self, node): 194 | HTMLTranslator.depart_document(self, node) 195 | self.html_body.pop(0) # pop the starting
off 196 | self.html_body.pop() # pop the ending
off 197 | 198 | # technique for visiting sections, without generating additional divs 199 | # see also: http://bit.ly/NHtyRx 200 | # the a is to support ::contents with ::sectnums: http://git.io/N1yC 201 | def visit_section(self, node): 202 | for id_attribute in node.attributes['ids']: 203 | self.body.append('\n' % id_attribute) 204 | self.section_level += 1 205 | 206 | def depart_section(self, node): 207 | self.section_level -= 1 208 | 209 | def visit_literal_block(self, node): 210 | classes = node.attributes['classes'] 211 | if len(classes) >= 2 and classes[0] == 'code': 212 | language = classes[1] 213 | del classes[:] 214 | self.body.append(self.starttag(node, 'pre', lang=language)) 215 | elif default_highlight_language is not None: 216 | self.body.append(self.starttag(node, 'pre', lang=default_highlight_language)) 217 | else: 218 | self.body.append(self.starttag(node, 'pre')) 219 | 220 | def visit_doctest_block(self, node): 221 | self.body.append(self.starttag(node, 'pre', lang='pycon')) 222 | 223 | # always wrap two-backtick rst inline literals in , not 224 | # this also avoids the generation of superfluous tags 225 | def visit_literal(self, node): 226 | self.body.append(self.starttag(node, 'code', suffix='')) 227 | 228 | def depart_literal(self, node): 229 | self.body.append('') 230 | 231 | def visit_table(self, node): 232 | classes = ' '.join(['docutils', self.settings.table_style]).strip() 233 | self.body.append( 234 | self.starttag(node, 'table', CLASS=classes)) 235 | 236 | def depart_table(self, node): 237 | self.body.append('\n') 238 | 239 | def depart_image(self, node): 240 | uri = node['uri'] 241 | ext = os.path.splitext(uri)[1].lower() 242 | # we need to swap RST's use of `object` with `img` tags 243 | # see http://git.io/5me3dA 244 | if ext == ".svg": 245 | # preserve essential attributes 246 | atts = {} 247 | for attribute, value in node.attributes.items(): 248 | # we have no time for empty values 249 | if value: 250 | if attribute == "uri": 251 | atts['src'] = value 252 | else: 253 | atts[attribute] = value 254 | 255 | # toss off `object` tag 256 | self.body.pop() 257 | # add on `img` with attributes 258 | self.body.append(self.starttag(node, 'img', **atts)) 259 | HTMLTranslator.depart_image(self, node) 260 | 261 | 262 | def kbd(name, rawtext, text, lineno, inliner, options={}, content=[]): 263 | return [nodes.raw('', '%s' % text, format='html')], [] 264 | 265 | 266 | def main(): 267 | """ 268 | Parses the given ReST file or the redirected string input and returns the 269 | HTML body. 270 | 271 | Usage: rest2html < README.rst 272 | rest2html README.rst 273 | """ 274 | try: 275 | text = codecs.open(sys.argv[1], 'r', 'utf-8').read() 276 | except IOError: # given filename could not be found 277 | return '' 278 | except IndexError: # no filename given 279 | if sys.version_info[0] < 3: # python 2.x 280 | text = sys.stdin.read() 281 | else: # python 3 282 | input_stream = io.TextIOWrapper(sys.stdin.buffer, encoding='utf-8') 283 | text = input_stream.read() 284 | 285 | writer = Writer() 286 | writer.translator_class = GitHubHTMLTranslator 287 | 288 | roles.register_canonical_role('kbd', kbd) 289 | 290 | # Render source code in Sphinx doctest blocks 291 | directives.register_directive('doctest', DoctestDirective) 292 | 293 | # Set default highlight language 294 | directives.register_directive('highlight', HighlightDirective) 295 | 296 | parts = publish_parts(text, writer=writer, settings_overrides=SETTINGS) 297 | if 'html_body' in parts: 298 | html = parts['html_body'] 299 | 300 | # publish_parts() in python 2.x return dict values as Unicode type 301 | # in py3k Unicode is unavailable and values are of str type 302 | if isinstance(html, str): 303 | return html 304 | else: 305 | return html.encode('utf-8') 306 | return '' 307 | 308 | if __name__ == '__main__': 309 | if sys.version_info[0] < 3: # python 2.x 310 | sys.stdout.write("%s%s" % (main(), "\n")) 311 | else: # python 3 312 | output_stream = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8') 313 | output_stream.write("%s%s" % (main(), "\n")) 314 | sys.stdout.flush() 315 | -------------------------------------------------------------------------------- /lib/github/markup.rb: -------------------------------------------------------------------------------- 1 | begin 2 | require "linguist" 3 | rescue LoadError 4 | # Rely on extensions instead. 5 | end 6 | 7 | require "github/markup/command_implementation" 8 | require "github/markup/gem_implementation" 9 | 10 | module GitHub 11 | module Markups 12 | # all of supported markups: 13 | MARKUP_ASCIIDOC = :asciidoc 14 | MARKUP_CREOLE = :creole 15 | MARKUP_MARKDOWN = :markdown 16 | MARKUP_MEDIAWIKI = :mediawiki 17 | MARKUP_ORG = :org 18 | MARKUP_POD = :pod 19 | MARKUP_RDOC = :rdoc 20 | MARKUP_RST = :rst 21 | MARKUP_TEXTILE = :textile 22 | MARKUP_POD6 = :pod6 23 | end 24 | 25 | module Markup 26 | extend self 27 | 28 | @@markups = {} 29 | 30 | def markups 31 | @@markups 32 | end 33 | 34 | def markup_impls 35 | markups.values 36 | end 37 | 38 | def preload! 39 | markup_impls.each(&:load) 40 | end 41 | 42 | def render(filename, content, symlink: false, options: {}) 43 | if (impl = renderer(filename, content, symlink: symlink)) 44 | impl.render(filename, content, options: options) 45 | else 46 | content 47 | end 48 | end 49 | 50 | def render_s(symbol, content, options: {}) 51 | raise ArgumentError, 'Can not render a nil.' if content.nil? 52 | 53 | if markups.key?(symbol) 54 | markups[symbol].render(nil, content, options: options) 55 | else 56 | content 57 | end 58 | end 59 | 60 | def markup(symbol, gem_name, regexp, languages, opts = {}, &block) 61 | impl = GemImplementation.new(regexp, languages, gem_name, &block) 62 | markup_impl(symbol, impl) 63 | end 64 | 65 | def markup_impl(symbol, impl) 66 | if markups.key?(symbol) 67 | raise ArgumentError, "The '#{symbol}' symbol is already defined." 68 | end 69 | markups[symbol] = impl 70 | end 71 | 72 | def command(symbol, command, regexp, languages, name, &block) 73 | if File.exist?(file = File.dirname(__FILE__) + "/commands/#{command}") 74 | command = file 75 | end 76 | 77 | impl = CommandImplementation.new(regexp, languages, command, name, &block) 78 | markup_impl(symbol, impl) 79 | end 80 | 81 | def can_render?(filename, content, symlink: false) 82 | renderer(filename, content, symlink: symlink) != nil 83 | end 84 | 85 | def renderer(filename, content, symlink: false) 86 | language = language(filename, content, symlink: symlink) 87 | markup_impls.find do |impl| 88 | impl.match?(filename, language) 89 | end 90 | end 91 | 92 | def language(filename, content, symlink: false) 93 | return unless defined?(::Linguist) 94 | 95 | blob = Linguist::Blob.new(filename, content, symlink: symlink) 96 | Linguist.detect(blob, allow_empty: true) 97 | end 98 | 99 | # Define markups 100 | markups_rb = File.dirname(__FILE__) + '/markups.rb' 101 | instance_eval File.read(markups_rb), markups_rb 102 | end 103 | end 104 | -------------------------------------------------------------------------------- /lib/github/markup/command_implementation.rb: -------------------------------------------------------------------------------- 1 | require "open3" 2 | require "github/markup/implementation" 3 | 4 | 5 | module GitHub 6 | module Markup 7 | class CommandError < RuntimeError 8 | end 9 | 10 | class CommandImplementation < Implementation 11 | attr_reader :command, :block, :name 12 | 13 | def initialize(regexp, languages, command, name, &block) 14 | super(regexp, languages) 15 | @command = command.to_s 16 | @block = block 17 | @name = name 18 | end 19 | 20 | def render(filename, content, options: {}) 21 | rendered = execute(command, content) 22 | rendered = rendered.to_s.empty? ? content : rendered 23 | call_block(rendered, content) 24 | end 25 | 26 | private 27 | def call_block(rendered, content) 28 | if block && block.arity == 2 29 | block.call(rendered, content) 30 | elsif block 31 | block.call(rendered) 32 | else 33 | rendered 34 | end 35 | end 36 | 37 | def execute(command, target) 38 | # capture3 blocks until both buffers are written to and the process terminates, but 39 | # it won't allow either buffer to fill up 40 | stdout, stderr, status = Open3.capture3(*command, stdin_data: target) 41 | 42 | raise CommandError.new(stderr) unless status.success? 43 | sanitize(stdout, target.encoding) 44 | end 45 | 46 | def sanitize(input, encoding) 47 | input.gsub("\r", '').force_encoding(encoding) 48 | end 49 | 50 | end 51 | end 52 | end 53 | -------------------------------------------------------------------------------- /lib/github/markup/gem_implementation.rb: -------------------------------------------------------------------------------- 1 | require "github/markup/implementation" 2 | 3 | module GitHub 4 | module Markup 5 | class GemImplementation < Implementation 6 | attr_reader :gem_name, :renderer 7 | 8 | def initialize(regexp, languages, gem_name, &renderer) 9 | super(regexp, languages) 10 | @gem_name = gem_name.to_s 11 | @renderer = renderer 12 | end 13 | 14 | def load 15 | return if defined?(@loaded) && @loaded 16 | require gem_name 17 | @loaded = true 18 | end 19 | 20 | def render(filename, content, options: {}) 21 | load 22 | renderer.call(filename, content, options: options) 23 | end 24 | 25 | def name 26 | gem_name 27 | end 28 | end 29 | end 30 | end 31 | -------------------------------------------------------------------------------- /lib/github/markup/implementation.rb: -------------------------------------------------------------------------------- 1 | module GitHub 2 | module Markup 3 | class Implementation 4 | attr_reader :regexp 5 | attr_reader :languages 6 | 7 | def initialize(regexp, languages) 8 | @regexp = regexp 9 | 10 | if defined?(::Linguist) 11 | @languages = languages.map do |l| 12 | lang = Linguist::Language[l] 13 | raise "no match for language #{l.inspect}" if lang.nil? 14 | lang 15 | end 16 | end 17 | end 18 | 19 | def load 20 | # no-op by default 21 | end 22 | 23 | def render(filename, content, options: {}) 24 | raise NotImplementedError, "subclasses of GitHub::Markup::Implementation must define #render" 25 | end 26 | 27 | def match?(filename, language) 28 | if defined?(::Linguist) 29 | languages.include? language 30 | else 31 | file_ext_regexp =~ filename 32 | end 33 | end 34 | 35 | private 36 | 37 | def file_ext_regexp 38 | @file_ext_regexp ||= /\.(#{regexp})\z/ 39 | end 40 | end 41 | end 42 | end 43 | -------------------------------------------------------------------------------- /lib/github/markup/markdown.rb: -------------------------------------------------------------------------------- 1 | require "github/markup/implementation" 2 | 3 | module GitHub 4 | module Markup 5 | class Markdown < Implementation 6 | MARKDOWN_GEMS = { 7 | "commonmarker" => proc { |content, options: {}| 8 | commonmarker_opts = [:GITHUB_PRE_LANG].concat(options.fetch(:commonmarker_opts, [])) 9 | commonmarker_exts = options.fetch(:commonmarker_exts, [:tagfilter, :autolink, :table, :strikethrough]) 10 | CommonMarker.render_html(content, commonmarker_opts, commonmarker_exts) 11 | }, 12 | "github/markdown" => proc { |content, options: {}| 13 | GitHub::Markdown.render(content) 14 | }, 15 | "redcarpet" => proc { |content, options: {}| 16 | Redcarpet::Markdown.new(Redcarpet::Render::HTML).render(content) 17 | }, 18 | "rdiscount" => proc { |content, options: {}| 19 | RDiscount.new(content).to_html 20 | }, 21 | "maruku" => proc { |content, options: {}| 22 | Maruku.new(content).to_html 23 | }, 24 | "kramdown" => proc { |content, options: {}| 25 | Kramdown::Document.new(content).to_html 26 | }, 27 | "bluecloth" => proc { |content, options: {}| 28 | BlueCloth.new(content).to_html 29 | }, 30 | } 31 | 32 | def initialize 33 | super( 34 | /md|mkdn?|mdwn|mdown|markdown|mdx|litcoffee/i, 35 | ["Markdown", "MDX", "Literate CoffeeScript"]) 36 | end 37 | 38 | def load 39 | return if @renderer 40 | MARKDOWN_GEMS.each do |gem_name, renderer| 41 | if try_require(gem_name) 42 | @renderer = renderer 43 | return 44 | end 45 | end 46 | raise LoadError, "no suitable markdown gem found" 47 | end 48 | 49 | def render(filename, content, options: {}) 50 | load 51 | @renderer.call(content, options: options) 52 | end 53 | 54 | def name 55 | "markdown" 56 | end 57 | 58 | private 59 | def try_require(file) 60 | require file 61 | true 62 | rescue LoadError 63 | false 64 | end 65 | end 66 | end 67 | end 68 | -------------------------------------------------------------------------------- /lib/github/markup/rdoc.rb: -------------------------------------------------------------------------------- 1 | require "github/markup/implementation" 2 | require "rdoc" 3 | require "rdoc/markup/to_html" 4 | 5 | module GitHub 6 | module Markup 7 | class RDoc < Implementation 8 | def initialize 9 | super(/rdoc/, ["RDoc"]) 10 | end 11 | 12 | def render(filename, content, options: {}) 13 | if ::RDoc::VERSION.to_i >= 4 14 | h = ::RDoc::Markup::ToHtml.new(::RDoc::Options.new) 15 | else 16 | h = ::RDoc::Markup::ToHtml.new 17 | end 18 | h.convert(content) 19 | end 20 | 21 | def name 22 | "rdoc" 23 | end 24 | end 25 | end 26 | end 27 | -------------------------------------------------------------------------------- /lib/github/markups.rb: -------------------------------------------------------------------------------- 1 | require "github/markup/markdown" 2 | require "github/markup/rdoc" 3 | require "shellwords" 4 | 5 | markup_impl(::GitHub::Markups::MARKUP_MARKDOWN, ::GitHub::Markup::Markdown.new) 6 | 7 | markup(::GitHub::Markups::MARKUP_TEXTILE, :redcloth, /textile/, ["Textile"]) do |filename, content, options: {}| 8 | RedCloth.new(content).to_html 9 | end 10 | 11 | markup_impl(::GitHub::Markups::MARKUP_RDOC, GitHub::Markup::RDoc.new) 12 | 13 | markup(::GitHub::Markups::MARKUP_ORG, 'org-ruby', /org/, ["Org"]) do |filename, content, options: {}| 14 | Orgmode::Parser.new(content, { 15 | :allow_include_files => false, 16 | :skip_syntax_highlight => true 17 | }).to_html 18 | end 19 | 20 | markup(::GitHub::Markups::MARKUP_CREOLE, :creole, /creole/, ["Creole"]) do |filename, content, options: {}| 21 | Creole.creolize(content) 22 | end 23 | 24 | markup(::GitHub::Markups::MARKUP_MEDIAWIKI, :wikicloth, /mediawiki|wiki/, ["MediaWiki"]) do |filename, content, options: {}| 25 | wikicloth = WikiCloth::WikiCloth.new(:data => content) 26 | WikiCloth::WikiBuffer::HTMLElement::ESCAPED_TAGS << 'tt' unless WikiCloth::WikiBuffer::HTMLElement::ESCAPED_TAGS.include?('tt') 27 | wikicloth.to_html(:noedit => true) 28 | end 29 | 30 | markup(::GitHub::Markups::MARKUP_ASCIIDOC, :asciidoctor, /adoc|asc(iidoc)?/, ["AsciiDoc"]) do |filename, content, options: {}| 31 | attributes = { 32 | 'showtitle' => '@', 33 | 'idprefix' => '', 34 | 'idseparator' => '-', 35 | 'sectanchors' => nil, 36 | 'env' => 'github', 37 | 'env-github' => '', 38 | 'source-highlighter' => 'html-pipeline' 39 | } 40 | if filename 41 | attributes['docname'] = File.basename(filename, (extname = File.extname(filename))) 42 | attributes['docfilesuffix'] = attributes['outfilesuffix'] = extname 43 | else 44 | attributes['outfilesuffix'] = '.adoc' 45 | end 46 | Asciidoctor::Compliance.unique_id_start_index = 1 47 | Asciidoctor.convert(content, :safe => :secure, :attributes => attributes) 48 | end 49 | 50 | command( 51 | ::GitHub::Markups::MARKUP_RST, 52 | "python3 #{Shellwords.escape(File.dirname(__FILE__))}/commands/rest2html", 53 | /re?st(\.txt)?/, 54 | ["reStructuredText"], 55 | "restructuredtext" 56 | ) 57 | 58 | command(::GitHub::Markups::MARKUP_POD6, :pod62html, /pod6/, ["Pod 6"], "pod6") 59 | command(::GitHub::Markups::MARKUP_POD, :pod2html, /pod/, ["Pod"], "pod") 60 | -------------------------------------------------------------------------------- /script/bootstrap: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | set -e 4 | 5 | cd $(dirname "$0")/.. 6 | 7 | bundle install 8 | pip3 install docutils 9 | -------------------------------------------------------------------------------- /script/bootstrap.contrib: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | set -e 4 | 5 | cd $(dirname "$0")/.. 6 | 7 | bundle install --path vendor/bundle 8 | virtualenv vendor/python && source vendor/python/bin/activate 9 | pip install docutils 10 | 11 | echo "" 12 | echo "*** DONE ***" 13 | echo "" 14 | echo "activate python environment with 'source vendor/python/bin/activate'" 15 | echo "run tests with 'bundle exec rake'" 16 | -------------------------------------------------------------------------------- /script/cibuild: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | set -e 4 | 5 | # GC customizations 6 | export RUBY_GC_MALLOC_LIMIT=79000000 7 | export RUBY_HEAP_MIN_SLOTS=800000 8 | export RUBY_HEAP_FREE_MIN=100000 9 | export RUBY_HEAP_SLOTS_INCREMENT=400000 10 | export RUBY_HEAP_SLOTS_GROWTH_FACTOR=1 11 | 12 | export PATH="/usr/share/rbenv/shims:$PATH" 13 | export RBENV_VERSION="1.9.3" 14 | 15 | # bootstrap gem environment changes 16 | echo "Bootstrapping gem environment ..." 17 | 18 | script/bootstrap --local 19 | 20 | rake 21 | -------------------------------------------------------------------------------- /test/fixtures/fail.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | echo "failure message">&2 && false 4 | -------------------------------------------------------------------------------- /test/markup_test.rb: -------------------------------------------------------------------------------- 1 | # encoding: utf-8 2 | 3 | $LOAD_PATH.unshift File.dirname(__FILE__) + "/../lib" 4 | 5 | require 'github/markup' 6 | require 'minitest/autorun' 7 | require 'html/pipeline' 8 | require 'nokogiri' 9 | require 'nokogiri/diff' 10 | 11 | def normalize_html(text) 12 | text.strip 13 | .gsub(/\s\s+/,' ') 14 | .gsub(/\p{Pi}|\p{Pf}|&quot;/u,'"') 15 | .gsub("\u2026",'...') 16 | end 17 | 18 | def assert_html_equal(expected, actual, msg = nil) 19 | assertion = Proc.new do 20 | expected_doc = Nokogiri::HTML(expected) {|config| config.noblanks} 21 | actual_doc = Nokogiri::HTML(actual) {|config| config.noblanks} 22 | 23 | expected_doc.search('//text()').each {|node| node.content = normalize_html node.content} 24 | actual_doc.search('//text()').each {|node| node.content = normalize_html node.content} 25 | 26 | ignore_changes = {"+" => Regexp.union(/^\s*id=".*"\s*$/), "-" => nil} 27 | expected_doc.diff(actual_doc) do |change, node| 28 | if change != ' ' && !node.blank? then 29 | break unless node.to_html =~ ignore_changes[change] 30 | end 31 | end 32 | end 33 | assert(assertion.call, msg) 34 | end 35 | 36 | class MarkupTest < Minitest::Test 37 | class MarkupFilter < HTML::Pipeline::Filter 38 | def call 39 | filename = context[:filename] 40 | GitHub::Markup.render(filename, File.read(filename)).strip.force_encoding("utf-8") 41 | end 42 | end 43 | 44 | Pipeline = HTML::Pipeline.new [ 45 | MarkupFilter, 46 | HTML::Pipeline::SanitizationFilter 47 | ] 48 | 49 | Dir['test/markups/README.*'].each do |readme| 50 | next if readme =~ /html$/ 51 | markup = readme.split('/').last.gsub(/^README\./, '') 52 | 53 | define_method "test_#{markup}" do 54 | skip "Skipping MediaWiki test because wikicloth is currently not compatible with JRuby." if markup == "mediawiki" && RUBY_PLATFORM == "java" 55 | source = File.read(readme) 56 | expected_file = "#{readme}.html" 57 | expected = File.read(expected_file).rstrip 58 | actual = Pipeline.to_html(nil, :filename => readme) 59 | 60 | if source != expected 61 | assert(source != actual, "#{markup} did not render anything") 62 | end 63 | 64 | diff = IO.popen("diff -u - #{expected_file}", 'r+') do |f| 65 | f.write actual 66 | f.close_write 67 | f.read 68 | end 69 | 70 | if ENV['UPDATE'] 71 | File.open(expected_file, 'w') { |f| f.write actual } 72 | end 73 | 74 | assert_html_equal expected, actual, <Title') 83 | assert_equal true, GitHub::Markup.can_render?('README.markdown', '=== Title') 84 | assert_equal false, GitHub::Markup.can_render?('README.cmd', 'echo 1') 85 | assert_equal true, GitHub::Markup.can_render?('README.litcoffee', 'Title') 86 | end 87 | 88 | def test_each_render_has_a_name 89 | assert_equal "markdown", GitHub::Markup.renderer('README.md', '=== Title').name 90 | assert_equal "redcloth", GitHub::Markup.renderer('README.textile', '* One').name 91 | assert_equal "rdoc", GitHub::Markup.renderer('README.rdoc', '* One').name 92 | assert_equal "org-ruby", GitHub::Markup.renderer('README.org', '* Title').name 93 | assert_equal "creole", GitHub::Markup.renderer('README.creole', '= Title =').name 94 | assert_equal "wikicloth", GitHub::Markup.renderer('README.wiki', '

Title

').name 95 | assert_equal "asciidoctor", GitHub::Markup.renderer('README.adoc', '== Title').name 96 | assert_equal "restructuredtext", GitHub::Markup.renderer('README.rst', 'Title').name 97 | assert_equal "pod", GitHub::Markup.renderer('README.pod', '=head1').name 98 | assert_equal "pod6", GitHub::Markup.renderer('README.pod6', '=begin pod').name 99 | end 100 | 101 | def test_rendering_by_symbol 102 | markup = '`test`' 103 | result = /

test<\/code><\/p>/ 104 | assert_match result, GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, markup).strip 105 | assert_match result, GitHub::Markup.render_s(GitHub::Markups::MARKUP_ASCIIDOC, markup).split.join 106 | end 107 | 108 | def test_raises_error_if_command_exits_non_zero 109 | GitHub::Markup.command(:doesntmatter, 'test/fixtures/fail.sh', /fail/, ['Java'], 'fail') 110 | assert GitHub::Markup.can_render?('README.java', 'stop swallowing errors') 111 | begin 112 | GitHub::Markup.render('README.java', "stop swallowing errors", symlink: false) 113 | rescue GitHub::Markup::CommandError => e 114 | assert_equal "failure message", e.message.strip 115 | else 116 | fail "an exception was expected but was not raised" 117 | end 118 | end 119 | 120 | def test_preserve_markup 121 | content = "Noël" 122 | assert_equal content.encoding.name, GitHub::Markup.render('Foo.rst', content).encoding.name 123 | end 124 | 125 | def test_commonmarker_options 126 | assert_equal "

hello world

\n", GitHub::Markup.render("test.md", "hello world") 127 | assert_equal "

hello world

\n", GitHub::Markup.render("test.md", "hello world", options: {commonmarker_opts: [:UNSAFE]}) 128 | 129 | assert_equal "

hello world

\n", GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "hello world") 130 | assert_equal "

hello world

\n", GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "hello world", options: {commonmarker_opts: [:UNSAFE]}) 131 | 132 | assert_equal "<style>.red{color: red;}</style>\n", GitHub::Markup.render("test.md", "", options: {commonmarker_opts: [:UNSAFE]}) 133 | assert_equal "\n", GitHub::Markup.render("test.md", "", options: {commonmarker_opts: [:UNSAFE], commonmarker_exts: [:autolink, :table, :strikethrough]}) 134 | 135 | assert_equal "<style>.red{color: red;}</style>\n", GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "", options: {commonmarker_opts: [:UNSAFE]}) 136 | assert_equal "\n", GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "", options: {commonmarker_opts: [:UNSAFE], commonmarker_exts: [:autolink, :table, :strikethrough]}) 137 | end 138 | end 139 | -------------------------------------------------------------------------------- /test/markups/README.asciidoc: -------------------------------------------------------------------------------- 1 | = Document Title 2 | // sectanchors will be ignored 3 | :sectanchors: 4 | 5 | == First Section 6 | 7 | * One 8 | * Two 9 | 10 | Refer to <> or <>. 11 | 12 | Navigate from {docname}{outfilesuffix} to xref:another-document.asciidoc[another document]. 13 | 14 | == Another Section 15 | 16 | NOTE: Here is some source code. 17 | 18 | ```ruby 19 | puts "Hello, World!" 20 | ``` 21 | 22 | * [ ] todo 23 | * [x] done 24 | 25 | == Another Section 26 | 27 | content 28 | -------------------------------------------------------------------------------- /test/markups/README.asciidoc.html: -------------------------------------------------------------------------------- 1 |

Document Title

2 |
3 |

First Section

4 |
5 |
6 |
    7 |
  • 8 |

    One

    9 |
    • 10 |
  • 11 |

    Two

    12 |
    • 13 |
14 |
15 |
16 |

Refer to Another Section or Another Section.

17 |
18 |
19 |

Navigate from README.asciidoc to another document.

20 |
21 |
22 |
23 |
24 |

Another Section

25 |
26 |
27 | 28 | 29 | 32 | 35 | 36 |
30 |
Note
31 | 		33 | Here is some source code. 34 |
37 |
38 |
39 |
40 | 
puts "Hello, World!"
41 |
42 |
43 |
44 |
    45 |
  • 46 |

    ❏ todo

    47 |
    • 48 |
  • 49 |

    ✓ done

    50 |
    • 51 |
52 |
53 |
54 |
55 |
56 |

Another Section

57 |
58 |
59 |

content

60 |
61 |
62 |
-------------------------------------------------------------------------------- /test/markups/README.creole: -------------------------------------------------------------------------------- 1 | = H1 = 2 | 3 | == H2 == 4 | 5 | paragraph of text that will be turned into a paragraph element. It can 6 | go over several lines with line breaks, it will be turned into a 7 | contiguous paragraph element. 8 | 9 | You can force a linebreak in your paragraph text\\thusly. 10 | 11 | 12 | * a list element 13 | ** sub list element 14 | * 2nd list element 15 | 16 | {{{ 17 | pre formatted text 18 | 19 | $ ls -la 20 | total 56 21 | drwxr-xr-x 6 nferrier users 4096 Jul 5 23:10 . 22 | drwxr-x--- 120 nferrier users 12288 Jul 5 19:36 .. 23 | drwxr-xr-x 2 nferrier users 4096 Jul 5 18:19 bin 24 | -rw-r--r-- 1 nferrier users 6 Jul 5 18:19 .gitignore 25 | drwxr-xr-x 4 nferrier users 4096 Jul 5 23:10 .hg 26 | -rw-r--r-- 1 nferrier users 1182 Jul 5 18:19 HISTORY.md 27 | -rw-r--r-- 1 nferrier users 562 Jul 5 18:19 .kick 28 | drwxr-xr-x 3 nferrier users 4096 Jul 5 18:19 lib 29 | -rw-r--r-- 1 nferrier users 1050 Jul 5 18:19 LICENSE 30 | -rw-r--r-- 1 nferrier users 1312 Jul 5 18:19 Rakefile 31 | -rw-r--r-- 1 nferrier users 3390 Jul 5 18:19 README.md 32 | drwxr-xr-x 3 nferrier users 4096 Jul 5 18:19 test 33 | }}} 34 | 35 | -------------------------------------------------------------------------------- /test/markups/README.creole.html: -------------------------------------------------------------------------------- 1 |

H1

H2

paragraph of text that will be turned into a paragraph element. It can go over several lines with line breaks, it will be turned into a contiguous paragraph element.

You can force a linebreak in your paragraph text
thusly.

    2 |
  • a list element
    • sub list element
    3 |
    • 4 |
  • 2nd list element
    • 5 | 
pre formatted text
 6 | 
 7 | $ ls -la
 8 | total 56
 9 | drwxr-xr-x   6 nferrier users  4096 Jul  5 23:10 .
10 | drwxr-x--- 120 nferrier users 12288 Jul  5 19:36 ..
11 | drwxr-xr-x   2 nferrier users  4096 Jul  5 18:19 bin
12 | -rw-r--r--   1 nferrier users     6 Jul  5 18:19 .gitignore
13 | drwxr-xr-x   4 nferrier users  4096 Jul  5 23:10 .hg
14 | -rw-r--r--   1 nferrier users  1182 Jul  5 18:19 HISTORY.md
15 | -rw-r--r--   1 nferrier users   562 Jul  5 18:19 .kick
16 | drwxr-xr-x   3 nferrier users  4096 Jul  5 18:19 lib
17 | -rw-r--r--   1 nferrier users  1050 Jul  5 18:19 LICENSE
18 | -rw-r--r--   1 nferrier users  1312 Jul  5 18:19 Rakefile
19 | -rw-r--r--   1 nferrier users  3390 Jul  5 18:19 README.md
20 | drwxr-xr-x   3 nferrier users  4096 Jul  5 18:19 test
-------------------------------------------------------------------------------- /test/markups/README.directives.rst: -------------------------------------------------------------------------------- 1 | ================================================== 2 | restructuredText (rst) directives and comments 3 | ================================================== 4 | 5 | Introduction 6 | ================= 7 | 8 | An rst directive starts with two periods, and has a keyword 9 | followed by two colons, like this:: 10 | 11 | .. MyDirective:: 12 | 13 | The rst parser is quite flexible and configurable. Directives 14 | may be added for specialized operations. Sphinx is a system 15 | that was designed for writing documentation, and, for example, 16 | readthedocs.org uses sphinx. 17 | 18 | Display of rst files at github needs to cover two distinct 19 | use-cases: 20 | 21 | - The github display is the primary method for displaying 22 | the file (e.g. for README.rst files) 23 | 24 | - The github display is incidental to the primary method 25 | for displaying the file (e.g. for readthedocs documentation) 26 | 27 | Currently, github handles the first case fine, but could 28 | confuse viewers for the second case, because sometimes 29 | content is missing from the github display. 30 | 31 | It would seem that one possibility for distinguishing these 32 | two cases is to add a github directive to control the display. 33 | 34 | Unfortunately, this would place a burden on every other rst 35 | parser to ignore the github directive (some of them will error 36 | on unknown directives). 37 | 38 | Instead, we can assign semantic content to specific comments. 39 | 40 | This is a fairly ugly hack, but it has the benefit of not 41 | requiring any document changes that would create problems with 42 | any conformant parser. 43 | 44 | 45 | The proposed special comment is:: 46 | 47 | .. github display [on | off] 48 | 49 | 50 | If you pass this the "on" value, then all unknown directives 51 | will be displayed as literal code blocks. If you pass this 52 | the "off" value, then unknown directives will not be displayed. 53 | 54 | In addition to controlling the display of literal code blocks, 55 | this also allows you to show comments specifically for github. 56 | 57 | For example, somebody could place this at the top of their file:: 58 | 59 | .. github display 60 | 61 | This file was designed to be viewed at readthedocs. Some 62 | content will not display properly when viewing using the 63 | github browser. 64 | 65 | Tests 66 | ========== 67 | 68 | By default, unknown directives should be displayed. 69 | 70 | .. UnknownDirective:: This is an unknown directive 71 | 72 | it has a lot of stuff underneath it 73 | 74 | But we can turn this off, and the next directive should 75 | not be displayed. 76 | 77 | .. github display off 78 | 79 | .. UnknownDirective:: This is an unknown directive 80 | 81 | it has a lot of stuff underneath it 82 | 83 | Or we can turn it back on... 84 | 85 | .. github display on 86 | 87 | .. UnknownDirective:: This is an unknown directive (3) 88 | 89 | it has a lot of stuff underneath it 90 | 91 | Here is a comment that should display at github 92 | 93 | .. github display 94 | 95 | YOU SHOULD SEE THIS! 96 | 97 | And here is a comment that should not display at github 98 | 99 | .. foobar 100 | 101 | YOU SHOULD NOT SEE THIS! 102 | 103 | This concludes the tests. 104 | -------------------------------------------------------------------------------- /test/markups/README.directives.rst.html: -------------------------------------------------------------------------------- 1 |

restructuredText (rst) directives and comments

2 | 3 |

Introduction

4 |

An rst directive starts with two periods, and has a keyword 5 | followed by two colons, like this:

6 | 
 7 | .. MyDirective::
 8 |
9 |

The rst parser is quite flexible and configurable. Directives 10 | may be added for specialized operations. Sphinx is a system 11 | that was designed for writing documentation, and, for example, 12 | readthedocs.org uses sphinx.

13 |

Display of rst files at github needs to cover two distinct 14 | use-cases:

15 |
    16 |
  • The github display is the primary method for displaying 17 | the file (e.g. for README.rst files)
    • 18 |
  • The github display is incidental to the primary method 19 | for displaying the file (e.g. for readthedocs documentation)
    • 20 |
21 |

Currently, github handles the first case fine, but could 22 | confuse viewers for the second case, because sometimes 23 | content is missing from the github display.

24 |

It would seem that one possibility for distinguishing these 25 | two cases is to add a github directive to control the display.

26 |

Unfortunately, this would place a burden on every other rst 27 | parser to ignore the github directive (some of them will error 28 | on unknown directives).

29 |

Instead, we can assign semantic content to specific comments.

30 |

This is a fairly ugly hack, but it has the benefit of not 31 | requiring any document changes that would create problems with 32 | any conformant parser.

33 |

The proposed special comment is:

34 | 
35 | .. github display [on | off]
36 |
37 |

If you pass this the "on" value, then all unknown directives 38 | will be displayed as literal code blocks. If you pass this 39 | the "off" value, then unknown directives will not be displayed.

40 |

In addition to controlling the display of literal code blocks, 41 | this also allows you to show comments specifically for github.

42 |

For example, somebody could place this at the top of their file:

43 | 
44 | .. github display
45 | 
46 |   This file was designed to be viewed at readthedocs.  Some
47 |   content will not display properly when viewing using the
48 |   github browser.
49 |
50 | 51 |

Tests

52 |

By default, unknown directives should be displayed.

53 | 
54 | .. UnknownDirective::  This is an unknown directive
55 | 
56 |       it has a lot of stuff underneath it
57 | 
58 |
59 |

But we can turn this off, and the next directive should 60 | not be displayed.

61 |

Or we can turn it back on...

62 | 
63 | .. UnknownDirective::  This is an unknown directive (3)
64 | 
65 |       it has a lot of stuff underneath it
66 | 
67 |
68 |

Here is a comment that should display at github

69 | 
70 | 
71 | YOU SHOULD SEE THIS!
72 |
73 |

And here is a comment that should not display at github

74 |

This concludes the tests.

-------------------------------------------------------------------------------- /test/markups/README.hidetitle.asciidoc: -------------------------------------------------------------------------------- 1 | = Not Shown 2 | :!showtitle: 3 | 4 | This test verifies the author can disable the document title by adding `:!showtitle:` to the document header. 5 | -------------------------------------------------------------------------------- /test/markups/README.hidetitle.asciidoc.html: -------------------------------------------------------------------------------- 1 |
2 |

This test verifies the author can disable the document title by adding :!showtitle: to the document header.

3 |
-------------------------------------------------------------------------------- /test/markups/README.litcoffee: -------------------------------------------------------------------------------- 1 | Literate CoffeeScript Test 2 | -------------------------- 3 | 4 | > Taken from https://github.com/jashkenas/coffee-script/blob/master/test/literate.litcoffee 5 | 6 | comment comment 7 | 8 | test "basic literate CoffeeScript parsing", -> 9 | ok yes 10 | 11 | now with a... 12 | 13 | test "broken up indentation", -> 14 | 15 | ... broken up ... 16 | 17 | do -> 18 | 19 | ... nested block. 20 | 21 | ok yes 22 | 23 | Code must be separated from text by a blank line. 24 | 25 | test "code blocks must be preceded by a blank line", -> 26 | 27 | The next line is part of the text and will not be executed. 28 | fail() 29 | 30 | ok yes 31 | 32 | Code in `backticks is not parsed` and... 33 | 34 | test "comments in indented blocks work", -> 35 | do -> 36 | do -> 37 | # Regular comment. 38 | 39 | ### 40 | Block comment. 41 | ### 42 | 43 | ok yes 44 | 45 | Regular [Markdown](http://example.com/markdown) features, 46 | like links and unordered lists, are fine: 47 | 48 | * I 49 | 50 | * Am 51 | 52 | * A 53 | 54 | * List 55 | 56 | Tabs work too: 57 | 58 | test "tabbed code", -> 59 | ok yes 60 | -------------------------------------------------------------------------------- /test/markups/README.litcoffee.html: -------------------------------------------------------------------------------- 1 |

Literate CoffeeScript Test

2 |
3 |

Taken from https://github.com/jashkenas/coffee-script/blob/master/test/literate.litcoffee

4 |
5 |

comment comment

6 | 
test "basic literate CoffeeScript parsing", ->
 7 |   ok yes
 8 |
9 |

now with a...

10 | 
test "broken up indentation", ->
11 |
12 |

... broken up ...

13 | 
  do ->
14 |
15 |

... nested block.

16 | 
    ok yes
17 |
18 |

Code must be separated from text by a blank line.

19 | 
test "code blocks must be preceded by a blank line", ->
20 |
21 |

The next line is part of the text and will not be executed. 22 | fail()

23 | 
  ok yes
24 |
25 |

Code in backticks is not parsed and...

26 | 
test "comments in indented blocks work", ->
27 |   do ->
28 |     do ->
29 |       # Regular comment.
30 | 
31 |       ###
32 |         Block comment.
33 |       ###
34 | 
35 |       ok yes
36 |
37 |

Regular Markdown features, 38 | like links and unordered lists, are fine:

39 |
    40 |
  • 41 |

    I

    42 |
    • 43 |
  • 44 |

    Am

    45 |
    • 46 |
  • 47 |

    A

    48 |
    • 49 |
  • 50 |

    List

    51 |
    • 52 |
53 |

Tabs work too:

54 |

test "tabbed code", -> 55 | ok yes

-------------------------------------------------------------------------------- /test/markups/README.long.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | Robot Framework 7.0 3 | =================== 4 | 5 | .. default-role:: code 6 | 7 | `Robot Framework`_ 7.0 is a new major release with highly enhanced listener interface 8 | (`#3296`_), native `VAR` syntax for creating variables (`#3761`_), support for 9 | mixing embedded and normal arguments with library keywords (`#4710`_), JSON 10 | result format (`#4847`_) and various other enhancements and bug fixes. 11 | 12 | Robot Framework 7.0 was released on Thursday January 11, 2024. Questions and comments 13 | related to the release can be sent to the `#devel` channel on `Robot Framework Slack`_ 14 | and possible bugs submitted to the `issue tracker`_. 15 | 16 | .. _Robot Framework: http://robotframework.org 17 | .. _Robot Framework Foundation: http://robotframework.org/foundation 18 | 19 | 20 | .. _pip: http://pip-installer.org 21 | .. _PyPI: https://pypi.python.org/pypi/robotframework 22 | .. _issue tracker milestone: https://github.com/robotframework/robotframework/milestone/64 23 | .. _issue tracker: https://github.com/robotframework/robotframework/issues 24 | .. _Slack: http://slack.robotframework.org 25 | .. _Robot Framework Slack: Slack_ 26 | .. _installation instructions: ../../INSTALL.rst 27 | 28 | .. contents:: 29 | :depth: 2 30 | :local: 31 | 32 | Installation 33 | ============ 34 | 35 | If you have pip_ installed, just run 36 | 37 | :: 38 | 39 | pip install --upgrade robotframework 40 | 41 | to install the latest available stable release or use 42 | 43 | :: 44 | 45 | pip install robotframework==7.0 46 | 47 | to install exactly this version. Alternatively you can download the package 48 | from PyPI_ and install it manually. For more details and other installation 49 | approaches, see the `installation instructions`_. 50 | 51 | Most important enhancements 52 | =========================== 53 | 54 | If you are interested to learn more about the new features in Robot Framework 7.0, 55 | join the `RoboCon conference`__ in February, 2024. `Pekka Klärck`_, Robot Framework 56 | lead developer, will go through the key features briefly in the `onsite conference`__ 57 | in Helsinki and more thoroughly in the `online edition`__. 58 | 59 | The conference has also dozens of other great talks, workshops and a lot of 60 | possibilities to meet other community members as well as developers of various 61 | tools and libraries in the ecosystem. All profits from the conference will be 62 | used for future Robot Framework development. 63 | 64 | .. _Pekka Klärck: https://github.com/pekkaklarck 65 | __ https://robocon.io 66 | __ https://robocon.io/#live-opening-the-conference 67 | __ https://robocon.io/#online-opening-the-conference-live 68 | 69 | Listener enhancements 70 | --------------------- 71 | 72 | Robot Framework's `listener interface`__ is a very powerful mechanism to get 73 | notifications about various events during execution and it also allows modifying 74 | data and results on the fly. It is not typically directly used by normal Robot 75 | Framework users, but they are likely to use tools that use it internally. 76 | The listener API has been significantly enhanced making it possible 77 | to create even more powerful and interesting tools in the future. 78 | 79 | __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#listener-interface 80 | 81 | Support keywords and control structures with listener version 3 82 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 83 | 84 | The major limitation with the listener API has been that the listener 85 | API version 2 only supports getting notifications, not making modifications, 86 | and that the more powerful listener API version 3 has only supported suites 87 | and tests/tasks. 88 | 89 | The biggest enhancement in the whole Robot Framework 7.0 is that the listener 90 | version 3 has been extended to support also keywords and control structures (`#3296`_). 91 | For example, a listener having the following methods prints information 92 | about started keywords and ended WHILE loops: 93 | 94 | .. code:: python 95 | 96 | from robot import result, running 97 | 98 | 99 | def start_keyword(data: running.Keyword, result: result.Keyword): 100 | print(f"Keyword '{result.full_name}' used on line {data.lineno} started.") 101 | 102 | 103 | def end_while(data: running.While, result: result.While): 104 | print(f"WHILE loop on line {data.lineno} ended with status {result.status} " 105 | f"after {len(result.body)} iterations.") 106 | 107 | With keyword calls it is possible to also get more information about the actually 108 | executed keyword. For example, the following listener prints some information 109 | about the executed keyword and the library it belongs to: 110 | 111 | .. code:: python 112 | 113 | from robot.running import Keyword as KeywordData, LibraryKeyword 114 | from robot.result import Keyword as KeywordResult 115 | 116 | 117 | def start_library_keyword(data: KeywordData, 118 | implementation: LibraryKeyword, 119 | result: KeywordResult): 120 | library = implementation.owner 121 | print(f"Keyword '{implementation.name}' is implemented in library " 122 | f"'{library.name}' at '{implementation.source}' on line " 123 | f"{implementation.lineno}. The library has {library.scope.name} " 124 | f"scope and the current instance is {library.instance}.") 125 | 126 | As the above example already illustrated, it is even possible to get an access to 127 | the actual library instance. This means that listeners can inspect the library 128 | state and also modify it. With user keywords it is even possible to modify 129 | the keyword itself or, via the `owner` resource file, any other keyword in 130 | the resource file. 131 | 132 | Listeners can also modify results if needed. Possible use cases include hiding 133 | sensitive information and adding more details to results based on external sources. 134 | 135 | Notice that although listener can change status of any executed keyword or control 136 | structure, that does not directly affect the status of the executed test. In general 137 | listeners cannot directly fail keywords so that execution would stop or handle 138 | failures so that execution would continue. This kind of functionality may be 139 | added in the future if there are needs. 140 | 141 | The new listener version 3 methods are so powerful and versatile that going them 142 | through thoroughly in these release notes is not possible. For more examples, you 143 | can see the `acceptance tests`__ using the methods in various interesting and even 144 | crazy ways. 145 | 146 | __ https://github.com/robotframework/robotframework/tree/master/atest/testdata/output/listener_interface/body_items_v3 147 | 148 | Listener version 3 is the default listener version 149 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 150 | 151 | Earlier listeners always needed to specify the API version they used with the 152 | `ROBOT_LISTENER_API_VERSION` attribute. Now that the listener version 3 got 153 | the new methods, it is considered so much more powerful than the version 2 154 | that it was made the default listener version (`#4910`_). 155 | 156 | The listener version 2 continues to work, but using it requires specifying 157 | the listener version as earlier. The are no plans to deprecate the listener 158 | version 2, but we nevertheless highly recommend using the version 3 whenever 159 | possible. 160 | 161 | Libraries can register themselves as listeners by using string `SELF` 162 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 163 | 164 | Listeners are typically enabled from the command line, but libraries 165 | can register listeners as well. Often libraries themselves want to act 166 | as listeners, and that has earlier required using `self.ROBOT_LIBRARY_LISTENER = self` 167 | in the `__init__` method. Robot Framework 7.0 makes it possible to use string 168 | `SELF` (case-insensitive) for this purpose as well (`#4910`_), which means 169 | that a listener can be specified as a class attribute and not only in `__init__`. 170 | This is especially convenient when using the `@library` decorator: 171 | 172 | .. code:: python 173 | 174 | from robot.api.deco import keyword, library 175 | 176 | 177 | @library(listener='SELF') 178 | class Example: 179 | 180 | def start_suite(self, data, result): 181 | ... 182 | 183 | @keyword 184 | def example(self, arg): 185 | ... 186 | 187 | Nicer API for modifying keyword arguments 188 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 189 | 190 | Modifying keyword call arguments programmatically has been made more convenient 191 | (`#5000`_). This enhancement eases modifying arguments using the new listener 192 | version 3 `start/end_keyword` methods. 193 | 194 | Paths are passed to version 3 listeners as `pathlib.Path` objects 195 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 196 | 197 | Listeners have methods like `output_file` and `log_file` that are called when 198 | result files are ready so that they get the file path as an argument. Earlier 199 | paths were strings, but nowadays listener version 3 methods get them as 200 | more convenient `pathlib.Path`__ objects. 201 | 202 | __ https://docs.python.org/3/library/pathlib.html 203 | 204 | Native `VAR` syntax 205 | ------------------- 206 | 207 | The new `VAR` syntax (`#3761`_) makes it possible to create local variables 208 | as well as global, suite and test/task scoped variables dynamically during 209 | execution. The motivation is to have a more convenient syntax than using 210 | the `Set Variable` keyword for creating local variables and to unify 211 | the syntax for creating variables in different scopes. Except for the mandatory 212 | `VAR` marker, the syntax is also the same as when creating variables in the 213 | Variables section. The syntax is best explained with examples: 214 | 215 | .. code:: robotframework 216 | 217 | *** Test Cases *** 218 | Example 219 | # Create a local variable `${local}` with a value `value`. 220 | VAR ${local} value 221 | 222 | # Create a variable that is available throughout the whole suite. 223 | # Supported scopes are GLOBAL, SUITE, TEST, TASK and LOCAL (default). 224 | VAR ${suite} value scope=SUITE 225 | 226 | # Validate created variables. 227 | Should Be Equal ${local} value 228 | Should Be Equal ${suite} value 229 | 230 | Example continued 231 | # Suite level variables are seen also by subsequent tests. 232 | Should Be Equal ${suite} value 233 | 234 | When creating `${scalar}` variables having long values, it is possible to split 235 | the value to multiple lines. Lines are joined together with a space by default, 236 | but that can be changed with the `separator` configuration option. Similarly as 237 | in the Variables section, it is possible to create also `@{list}` and `&{dict}` 238 | variables. Unlike in the Variables section, variables can be created conditionally 239 | using IF/ELSE structures: 240 | 241 | .. code:: robotframework 242 | 243 | *** Test Cases *** 244 | Long value 245 | VAR ${long} 246 | ... This value is rather long. 247 | ... It has been split to multiple lines. 248 | ... Parts will be joined together with a space. 249 | 250 | Multiline 251 | VAR ${multiline} 252 | ... First line. 253 | ... Second line. 254 | ... Last line. 255 | ... separator=\n 256 | 257 | List 258 | # Creates a list with three items. 259 | VAR @{list} a b c 260 | 261 | Dictionary 262 | # Creates a dictionary with two items. 263 | VAR &{dict} key=value second=item 264 | 265 | Normal IF 266 | IF 1 > 0 267 | VAR ${x} true value 268 | ELSE 269 | VAR ${x} false value 270 | END 271 | 272 | Inline IF 273 | IF 1 > 0 VAR ${x} true value ELSE VAR ${x} false value 274 | 275 | Mixed argument support with library keywords 276 | -------------------------------------------- 277 | 278 | User keywords got support to use both embedded and normal arguments in Robot 279 | Framework 6.1 (`#4234`__) and now that support has been added also to library keywords 280 | (`#4710`_). The syntax works so, that if a function or method implementing a keyword 281 | accepts more arguments than there are embedded arguments, the remaining arguments 282 | can be passed in as normal arguments. This is illustrated by the following example 283 | keyword: 284 | 285 | .. code:: python 286 | 287 | @keyword('Number of ${animals} should be') 288 | def example(animals, count): 289 | ... 290 | 291 | The above keyword could be used like this: 292 | 293 | .. code:: robotframework 294 | 295 | *** Test Cases *** 296 | Example 297 | Number of horses should be 2 298 | Number of horses should be count=2 299 | Number of dogs should be 3 300 | 301 | __ https://github.com/robotframework/robotframework/issues/4234 302 | 303 | JSON result format 304 | ------------------ 305 | 306 | Robot Framework 6.1 added support to `convert test/task data to JSON and back`__ 307 | and Robot Framework 7.0 extends the JSON serialization support to execution results 308 | (`#4847`_). One of the core use cases for data serialization was making it easy to 309 | transfer data between process and machines, and now it is also easy to pass results 310 | back. 311 | 312 | Also the built-in Rebot tool that is used for post-processing results supports 313 | JSON files both in output and in input. Creating JSON output files is done using 314 | the normal `--output` option so that the specified file has a `.json` extension:: 315 | 316 | rebot --output output.json output.xml 317 | 318 | When reading output files, JSON files are automatically recognized by 319 | the extension:: 320 | 321 | rebot output.json 322 | rebot output1.json output2.json 323 | 324 | When combining or merging results, it is possible to mix JSON and XML files:: 325 | 326 | rebot output1.xml output2.json 327 | rebot --merge original.xml rerun.json 328 | 329 | The JSON output file structure is documented in the `result.json` `schema file`__. 330 | 331 | The plan is to enhance the support for JSON output files in the future so that 332 | they could be created already during execution. For more details see issue `#3423`__. 333 | 334 | __ https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-6.1.rst#json-data-format 335 | __ https://github.com/robotframework/robotframework/tree/master/doc/schema#readme 336 | __ https://github.com/robotframework/robotframework/issues/3423 337 | 338 | Argument conversion enhancements 339 | -------------------------------- 340 | 341 | Automatic argument conversion is a very powerful feature that library developers 342 | can use to avoid converting arguments manually and to get more useful Libdoc 343 | documentation. There are two important new enhancements to it. 344 | 345 | Support for `Literal` 346 | ~~~~~~~~~~~~~~~~~~~~~ 347 | 348 | In Python, the Literal__ type makes it possible to type arguments so that type 349 | checkers accept only certain values. For example, this function only accepts 350 | strings `x`, `y` and `z`: 351 | 352 | .. code:: python 353 | 354 | def example(arg: Literal['x', 'y', 'z']): 355 | ... 356 | 357 | Robot Framework has been enhanced so that it validates that an argument having 358 | a `Literal` type can only be used with the specified values (`#4633`_). For 359 | example, using a keyword with the above implementation with a value `xxx` would 360 | fail. 361 | 362 | In addition to validation, arguments are also converted. For example, if an 363 | argument accepts `Literal[-1, 0, 1]`, used arguments are converted to 364 | integers and then validated. In addition to that, string matching is case, space, 365 | underscore and hyphen insensitive. In all cases exact matches have a precedence 366 | and the argument that is passed to the keyword is guaranteed to be in the exact 367 | format used with `Literal`. 368 | 369 | `Literal` conversion is in many ways similar to Enum__ conversion that Robot 370 | Framework has supported for long time. `Enum` conversion has benefits like 371 | being able to use a custom documentation and it is typically better when using 372 | the same type multiple times. In simple cases being able to just use 373 | `arg: Literal[...]` without defining a new type is very convenient, though. 374 | 375 | __ https://docs.python.org/3/library/typing.html#typing.Literal 376 | __ https://docs.python.org/3/library/enum.html 377 | 378 | Support "stringified" types like `'list[int]'` and `'int | float'` 379 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 380 | 381 | Python's type hinting syntax has evolved so that generic types can be parameterized 382 | like `list[int]` (new in `Python 3.9`__) and unions written as `int | float` 383 | (new in `Python 3.10`__). Using these constructs with older Python versions causes 384 | errors, but Python type checkers support also "stringified" type hints like 385 | `'list[int]'` and `'int | float'` that work regardless the Python version. 386 | 387 | Support for stringified generics and unions has now been added also to 388 | Robot Framework's argument conversion (`#4711`_). For example, 389 | the following typing now also works with Python 3.8: 390 | 391 | .. code:: python 392 | 393 | def example(a: 'list[int]', b: 'int | float'): 394 | ... 395 | 396 | These stringified types are also compatible with the Remote library API and other 397 | scenarios where using actual types is not possible. 398 | 399 | __ https://peps.python.org/pep-0585 400 | __ https://peps.python.org/pep-0604 401 | 402 | Tags set globally can be removed using `-tag` syntax 403 | ---------------------------------------------------- 404 | 405 | Individual tests and keywords can nowadays remove tags that have been set in 406 | the Settings section with `Test Tags` or `Keyword Tags` settings by using 407 | the `-tag` syntax with their own `[Tags]` setting (`#4374`_). For example, 408 | tests `T1` and `T3` below get tags `all` and `most`, and test `T2` gets 409 | tags `all` and `one`: 410 | 411 | .. code:: robotframework 412 | 413 | *** Settings *** 414 | Test Tags all most 415 | 416 | *** Test Cases *** 417 | T1 418 | No Operation 419 | T2 420 | [Tags] one -most 421 | No Operation 422 | T3 423 | No Operation 424 | 425 | With tests it is possible to get the same effect by using the `Default Tags` 426 | setting and overriding it where needed. That syntax is, however, considered 427 | deprecated (`#4365`__) and using the new `-tag` syntax is recommended. With 428 | keywords there was no similar functionality earlier. 429 | 430 | __ https://github.com/robotframework/robotframework/issues/4365 431 | 432 | Dynamic and hybrid library APIs support asynchronous execution 433 | -------------------------------------------------------------- 434 | 435 | Dynamic and hybrid libraries nowadays support asynchronous execution. 436 | In practice the special methods like `get_keyword_names` and `run_keyword` 437 | can be implemented as async methods (`#4803`_). 438 | 439 | Async support was added to the normal static library API in Robot Framework 440 | 6.1 (`#4089`_). A bug related to handling asynchronous keywords if execution 441 | is stopped gracefully has also been fixed (`#4808`_). 442 | 443 | .. _#4089: https://github.com/robotframework/robotframework/issues/4089 444 | 445 | Timestamps in result model and output.xml use standard format 446 | ------------------------------------------------------------- 447 | 448 | Timestamps used in the result model and stored to the output.xml file used custom 449 | format like `20231107 19:57:01.123` earlier. Non-standard formats are seldom 450 | a good idea, and in this case parsing the custom format turned out to be slow 451 | as well. 452 | 453 | Nowadays the result model stores timestamps as standard datetime_ objects and 454 | elapsed times as a timedelta_ (`#4258`_). This makes creating timestamps and 455 | operating with them more convenient and considerably faster. The new objects can 456 | be accessed via `start_time`, `end_time` and `elapsed_time` attributes that were 457 | added as forward compatibility already in Robot Framework 6.1 (`#4765`_). 458 | Old information is still available via the old `starttime`, `endtime` and 459 | `elapsedtime` attributes, so this change is fully backwards compatible. 460 | 461 | The timestamp format in output.xml has also been changed from the custom 462 | `YYYYMMDD HH:MM:SS.mmm` format to `ISO 8601`_ compatible 463 | `YYYY-MM-DDTHH:MM:SS.mmmmmm`. Using a standard format makes it 464 | easier to process output.xml files, but this change also has big positive 465 | performance effect. Now that the result model stores timestamps as datetime_ 466 | objects, formatting and parsing them with the available `isoformat()`__ and 467 | `fromisoformat()`__ methods is very fast compared to custom formatting and parsing. 468 | 469 | A related change is that instead of storing start and end times of each executed 470 | item in output.xml, we nowadays store their start and elapsed times. Elapsed times 471 | are represented as floats denoting seconds. Having elapsed times directly available 472 | is a lot more convenient than calculating them based on start and end times. 473 | Storing start and elapsed times also takes less space than storing start and end times. 474 | 475 | As the result of these changes, times are available in the result model and in 476 | output.xml in higher precision than earlier. Earlier times were stored in millisecond 477 | granularity, but nowadays they use microseconds. Logs and reports still use milliseconds, 478 | but that can be changed in the future if there are needs. 479 | 480 | Changes to output.xml are backwards incompatible and affect all external tools 481 | that process timestamps. This is discussed more in `Changes to output.xml`_ 482 | section below along with other output.xml changes. 483 | 484 | .. _datetime: https://docs.python.org/3/library/datetime.html#datetime-objects 485 | .. _timedelta: https://docs.python.org/3/library/datetime.html#timedelta-objects 486 | .. _#4765: https://github.com/robotframework/robotframework/issues/4765 487 | .. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601 488 | __ https://docs.python.org/3/library/datetime.html#datetime.datetime.isoformat 489 | __ https://docs.python.org/3/library/datetime.html#datetime.datetime.fromisoformat 490 | 491 | Dark mode support to report and log 492 | ----------------------------------- 493 | 494 | Report and log got a new dark mode (`#3725`_). It is enabled automatically based 495 | on browser and operating system preferences, but there is also a toggle to 496 | switch between the modes. 497 | 498 | Backwards incompatible changes 499 | ============================== 500 | 501 | Python 3.6 and 3.7 are no longer supported 502 | ------------------------------------------ 503 | 504 | Robot Framework 7.0 requires Python 3.8 or newer (`#4294`_). The last version 505 | that supports Python 3.6 and 3.7 is Robot Framework 6.1.1. 506 | 507 | Changes to output.xml 508 | --------------------- 509 | 510 | The output.xml file has changed in different ways making Robot Framework 7.0 511 | incompatible with external tools processing output.xml files until these tools 512 | are updated. We try to avoid this kind of breaking changes, but in this case 513 | especially the changes to timestamps were considered so important that we 514 | eventually would have needed to do them anyway. 515 | 516 | Due to the changes being relatively big, it can take some time before external 517 | tools are updated. To allow users to take Robot Framework 7.0 into use also 518 | if they depend on an incompatible tool, it is possible to use the new 519 | `--legacy-output` option both as part of execution and with the Rebot tool 520 | to generate output.xml files that are compatible with older versions. 521 | 522 | Timestamp related changes 523 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 524 | 525 | The biggest changes in output.xml are related to timestamps (`#4258`_). 526 | With earlier versions start and end times of executed items, as well as timestamps 527 | of the logged messages, were stored using a custom `YYYYMMDD HH:MM:SS.mmm` format, 528 | but nowadays the format is `ISO 8601`_ compatible `YYYY-MM-DDTHH:MM:SS.mmmmmm`. 529 | In addition to that, instead of saving start and end times to `starttime` and 530 | `endtime` attributes and message times to `timestamp`, start and elapsed times 531 | are now stored to `start` and `elapsed` attributes and message times to `time`. 532 | 533 | Examples: 534 | 535 | .. code:: xml 536 | 537 | 538 | Hello world! 539 | 540 | 541 | 542 | Hello world! 543 | 544 | 545 | The new format is standard compliant, contains more detailed times, makes the elapsed 546 | time directly available and makes the `` elements over 10% shorter. 547 | These are all great benefits, but we are still sorry for all the extra work 548 | this causes for those developing tools that process output.xml files. 549 | 550 | Keyword name related changes 551 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 552 | 553 | How keyword names are stored in output.xml has changed slightly (`#4884`_). 554 | With each executed keywords we store both the name of the keyword and the name 555 | of the library or resource file containing it. Earlier the latter was stored to 556 | attribute `library` also with resource files, but nowadays the attribute is generic 557 | `owner`. In addition to `owner` being a better name in general, it also 558 | matches the new `owner` attribute keywords in the result model have. 559 | 560 | Another change is that the original name stored with keywords using embedded 561 | arguments is nowadays in `source_name` attribute when it used to be in `sourcename`. 562 | This change was done to make the attribute consistent with the attribute in 563 | the result model. 564 | 565 | Examples: 566 | 567 | .. code:: xml 568 | 569 | 570 | ... 571 | ... 572 | 573 | 574 | ... 575 | ... 576 | 577 | Other changes 578 | ~~~~~~~~~~~~~ 579 | 580 | Nowadays keywords and control structures can have a message. Messages are represented 581 | as the text of the `` element, and they have been present already earlier with 582 | tests and suites. Related to this, control structured cannot anymore have ``. 583 | (`#4883`_) 584 | 585 | These changes should not cause problems for tools processing output.xml files, 586 | but storing messages with each failed keyword and control structure may 587 | increase the output.xml size. 588 | 589 | Schema updates 590 | ~~~~~~~~~~~~~~ 591 | 592 | The output.xml schema has been updated and can be found via 593 | https://github.com/robotframework/robotframework/tree/master/doc/schema/. 594 | 595 | Changes to result model 596 | ----------------------- 597 | 598 | There have been some changes to the result model that unfortunately affect 599 | external tools using it. The main motivation for these changes has been 600 | cleaning up the model before creating a JSON representation for it (`#4847`_). 601 | 602 | Changes related to keyword names 603 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 604 | 605 | The biggest changes are related to keyword names (`#4884`_). Earlier `Keyword` 606 | objects had a `name` attribute that contained the full keyword name like 607 | `BuiltIn.Log`. The actual keyword name and the name of the library or resource 608 | file that the keyword belonged to were in `kwname` and `libname` attributes, 609 | respectively. In addition to these, keywords using embedded arguments also had 610 | a `sourcename` attribute containing the original keyword name. 611 | 612 | Due to reasons explained in `#4884`_, the following changes have been made 613 | in Robot Framework 7.0: 614 | 615 | - Old `kwname` is renamed to `name`. This is consistent with the execution side `Keyword`. 616 | - Old `libname` is renamed to generic `owner`. 617 | - New `full_name` is introduced to replace the old `name`. 618 | - `sourcename` is renamed to `source_name`. 619 | - `kwname`, `libname` and `sourcename` are preserved as properties. They are considered 620 | deprecated, but accessing them does not cause a deprecation warning yet. 621 | 622 | The backwards incompatible part of this change is changing the meaning of the 623 | `name` attribute. It used to be a read-only property yielding the full name 624 | like `BuiltIn.Log`, but now it is a normal attribute that contains just the actual 625 | keyword name like `Log`. All other old attributes have been preserved as properties 626 | and code using them does not need to be updated immediately. 627 | 628 | Deprecated attributes have been removed 629 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 630 | 631 | The following attributes that were deprecated already in Robot Framework 4.0 632 | have been removed (`#4846`_): 633 | 634 | - `TestSuite.keywords`. Use `TestSuite.setup` and `TestSuite.teardown` instead. 635 | - `TestCase.keywords`. Use `TestCase.body`, `TestCase.setup` and `TestCase.teardown` instead. 636 | - `Keyword.keywords`. Use `Keyword.body` and `Keyword.teardown` instead. 637 | - `Keyword.children`. Use `Keyword.body` and `Keyword.teardown` instead. 638 | - `TestCase.critical`. The whole criticality concept has been removed. 639 | 640 | Additionally, `TestSuite.keywords` and `TestCase.keywords` have been removed 641 | from the execution model. 642 | 643 | Changes to parsing model 644 | ------------------------ 645 | 646 | There have been some changes also to the parsing model: 647 | 648 | - The node representing the deprecated `[Return]` setting has been renamed from 649 | `Return` to `ReturnSetting`. At the same time, the node representing the 650 | `RETURN` statement has been renamed from `ReturnStatement` to `Return` (`#4939`_). 651 | 652 | To ease transition, `ReturnSetting` has existed as an alias for `Return` starting 653 | from Robot Framework 6.1 (`#4656`_) and `ReturnStatement` is preserved as an alias 654 | now. In addition to that, the `ModelVisitor` base class has special handling for 655 | `visit_ReturnSetting` and `visit_ReturnStatement` visitor methods so that they work 656 | correctly with `ReturnSetting` and `ReturnStatement` with Robot Framework 6.1 and 657 | newer. Issue `#4939`_ explains this in more detail and has a concrete example 658 | how to support also older Robot Framework versions. 659 | 660 | - The node representing the `Test Tags` setting as well as the deprecated 661 | `Force Tags` setting has been renamed from `ForceTags` to `TestTags` (`#4385`_). 662 | `ModelVisitor` has special handling for the `visit_ForceTags` method so 663 | that it will continue to work also after the change. 664 | 665 | - The token type used with `AS` (or `WITH NAME`) in library imports has been changed 666 | to `Token.AS` (`#4375`_). `Token.WITH_NAME` still exists as an alias for `Token.AS`. 667 | 668 | - Statement `type` and `tokens` have been moved from `_fields` to `_attributes` (`#4912`_). 669 | This may affect debugging the model. 670 | 671 | .. _#4656: https://github.com/robotframework/robotframework/issues/4656 672 | 673 | Changes to Libdoc spec files 674 | ---------------------------- 675 | 676 | The following deprecated constructs have been removed from Libdoc spec files (`#4667`_): 677 | 678 | - `datatypes` have been removed from XML or JSON spec files. They were deprecated in 679 | favor of `typedocs` already in Robot Framework 5.0 (`#4160`_). 680 | - Type names are not anymore written to XML specs as content of the `` elements. 681 | The name is available as the `name` attribute of `` elements since 682 | Robot Framework 6.1 (`#4538`_). 683 | - `types` and `typedocs` attributes have been removed from arguments in JSON specs. 684 | The `type` attribute introduced in RF 6.1 (`#4538`_) needs to be used instead. 685 | 686 | Libdoc schema files have been updated and can be found via 687 | https://github.com/robotframework/robotframework/tree/master/doc/schema/. 688 | 689 | .. _#4160: https://github.com/robotframework/robotframework/issues/4160 690 | .. _#4538: https://github.com/robotframework/robotframework/issues/4538 691 | 692 | Changes to selecting tests with `--suite`, `--test` and `--include` 693 | ------------------------------------------------------------------- 694 | 695 | There are two changes related to selecting tests: 696 | 697 | - When using `--test` and `--include` together, tests matching either of them 698 | are selected (`#4721`_). Earlier tests need to match both options to be selected. 699 | 700 | - When selecting a suite using its parent suite as a prefix like `--suite parent.suite`, 701 | the given name must match the full suite name (`#4720`_). Earlier it was enough if 702 | the prefix matched the closest parent or parents. 703 | 704 | Other backwards incompatible changes 705 | ------------------------------------ 706 | 707 | - The default value of the `stdin` argument used with `Process` library keyword 708 | has been changed from `subprocess.PIPE` to `None` (`#4103`_). This change ought 709 | to avoid processes hanging in some cases. Those who depend on the old behavior 710 | need to use `stdin=PIPE` explicitly to enable that. 711 | 712 | - When type hints are specified as strings, they must use format `type`, `type[param]`, 713 | `type[p1, p2]` or `t1 | t2` (`#4711`_). Using other formats will cause errors taking 714 | keywords into use. In practice problems occur if the special characters `[`, `]`, `,` 715 | and `|` occur in unexpected places. For example, `arg: "Hello, world!"` will cause 716 | an error due to the comma. 717 | 718 | - `datetime`, `date` and `timedelta` objects are sent over the Remote interface 719 | differently than earlier (`#4784`_). They all used to be converted to strings, but 720 | nowadays `datetime` is sent as-is, `date` is converted to `datetime` and sent like 721 | that, and `timedelta` is converted to a `float` by using `timedelta.total_seconds()`. 722 | 723 | - Argument conversion support with `collections.abc.ByteString` has been removed (`#4983`_). 724 | The reason is that `ByteString` is deprecated and will be removed in Python 3.14. 725 | It has not been too often needed, but if you happen to use it, you can change 726 | `arg: ByteString` to `arg: bytes | bytearray` and the functionality 727 | stays exactly the same. 728 | 729 | - Paths passed to result file related listener version 3 methods like `output_file` 730 | and `log_file` have been changed from strings to `pathlib.Path` objects (`#4988`_). 731 | Most of the time both kinds of paths work interchangeably, so this change is unlikely 732 | to cause issues. If you need to handle these paths as strings, they can be converted 733 | by using `str(path)`. 734 | 735 | - `robot.utils.normalize` does not anymore support bytes (`#4936`_). 736 | 737 | - Deprecated `accept_plain_values` argument has been removed from the 738 | `timestr_to_secs` utility function (`#4861`_). 739 | 740 | Deprecations 741 | ============ 742 | 743 | `[Return]` setting 744 | ------------------ 745 | 746 | The `[Return]` setting for specifying the return value from user keywords has 747 | been "loudly" deprecated (`#4876`_). It has been "silently" deprecated since 748 | Robot Framework 5.0 when the much more versatile `RETURN` setting was introduced 749 | (`#4078`_), but now using it will cause a deprecation warning. The plan is to 750 | preserve the `[Return]` setting at least until Robot Framework 8.0. 751 | 752 | If you have lot of data that uses `[Return]`, the easiest way to update it is 753 | using the Robotidy_ tool that can convert `[Return]` to `RETURN` automatically. 754 | If you have data that is executed also with Robot Framework versions that do 755 | not support `RETURN`, you can use the `Return From Keyword` keyword instead. 756 | That keyword will eventually be deprecated and removed as well, though. 757 | 758 | .. _#4078: https://github.com/robotframework/robotframework/issues/4078 759 | .. _Robotidy: https://robotidy.readthedocs.io 760 | 761 | Singular section headers 762 | ------------------------ 763 | 764 | Using singular section headers like `*** Test Case ***` or `*** Setting ***` 765 | nowadays causes a deprecation warning (`#4432`_). They were silently deprecated 766 | in Robot Framework 6.0 for reasons explained in issue `#4431`_. 767 | 768 | .. _#4431: https://github.com/robotframework/robotframework/issues/4431 769 | 770 | Deprecated attributes in parsing, running and result models 771 | ----------------------------------------------------------- 772 | 773 | - In the parsing model, `For.variables`, `ForHeader.variables`, `Try.variable` and 774 | `ExceptHeader.variable` attributes have been deprecated in favor of the new `assign` 775 | attribute (`#4708`_). 776 | 777 | - In running and result models, `For.variables` and `TryBranch.variable` have been 778 | deprecated in favor of the new `assign` attribute (`#4708`_). 779 | 780 | - In the result model, control structures like `FOR` were earlier modeled so that they 781 | looked like keywords. Nowadays they are considered totally different objects and 782 | their keyword specific attributes `name`, `kwnane`, `libname`, `doc`, `args`, 783 | `assign`, `tags` and `timeout` have been deprecated (`#4846`_). 784 | 785 | - `starttime`, `endtime` and `elapsed` time attributes in the result model have been 786 | silently deprecated (`#4258`_). Accessing them does not yet cause a deprecation 787 | warning, but users are recommended to use `start_time`, `end_time` and 788 | `elapsed_time` attributes that are available since Robot Framework 6.1. 789 | 790 | - `kwname`, `libname` and `sourcename` attributes used by the `Keyword` object 791 | in the result model have been silently deprecated (`#4884`_). New code should use 792 | `name`, `owner` and `source_name` instead. 793 | 794 | Other deprecated features 795 | ------------------------- 796 | 797 | - Using embedded arguments with a variable that has a value not matching custom 798 | embedded argument patterns nowadays causes a deprecation warning (`#4524`_). 799 | Earlier variables used as embedded arguments were always accepted without 800 | validating values. 801 | 802 | - Using `FOR IN ZIP` loops with lists having different lengths without explicitly 803 | using `mode=SHORTEST` has been deprecated (`#4685`_). The strict mode where lengths 804 | must match will be the default mode in the future. 805 | 806 | - Various utility functions in the `robot.utils` package that are no longer used 807 | by Robot Framework itself, including the whole Python 2/3 compatibility layer, 808 | have been deprecated (`#4501`_). If you need some of these utils, you can copy 809 | their code to your own tool or library. This change may affect existing 810 | libraries and tools in the ecosystem. 811 | 812 | - `case_insensitive` and `whitespace_insensitive` arguments used by some 813 | Collections and String library keywords have been deprecated in favor of 814 | `ignore_case` and `ignore_whitespace`. The new arguments were added for 815 | consistency reasons (`#4954`_) and the old arguments will continue to work 816 | for the time being. 817 | 818 | - Passing time as milliseconds to the `elapsed_time_to_string` utility function 819 | has been deprecated (`#4862`_). 820 | 821 | Acknowledgements 822 | ================ 823 | 824 | Robot Framework development is sponsored by the `Robot Framework Foundation`_ 825 | and its over 60 member organizations. If your organization is using Robot Framework 826 | and benefiting from it, consider joining the foundation to support its 827 | development as well. 828 | 829 | Robot Framework 7.0 team funded by the foundation consists of `Pekka Klärck`_ and 830 | `Janne Härkönen `_ (part time). 831 | In addition to work done by them, the community has provided some great contributions: 832 | 833 | - `Ygor Pontelo `__ added async support to the 834 | dynamic and hybrid library APIs (`#4803`_) and fixed a bug with handling async 835 | keywords when execution is stopped gracefully (`#4808`_). 836 | 837 | - `Topi 'top1' Tuulensuu `__ fixed a performance regression 838 | when using `Run Keyword` so that the name of the executed keyword contains a variable 839 | (`#4659`_). 840 | 841 | - `Pasi Saikkonen `__ added dark mode to reports 842 | and logs (`#3725`_). 843 | 844 | - `René `__ added return type information to Libdoc's 845 | HTML output (`#3017`_), fixed `DotDict` equality comparisons (`#4956`_) and 846 | helped finalizing the dark mode support (`#3725`_). 847 | 848 | - `Robin `__ added type hints to modules that 849 | did not yet have them under the public `robot.api` package (`#4841`_). 850 | 851 | - `Mark Moberts `__ added case-insensitive list and 852 | dictionary comparison support to the Collections library (`#4343`_). 853 | 854 | - `Daniel Biehl `__ enhanced performance of traversing 855 | the parsing model using `ModelVisitor` (`#4934`_). 856 | 857 | Big thanks to Robot Framework Foundation, to community members listed above, and to 858 | everyone else who has tested preview releases, submitted bug reports, proposed 859 | enhancements, debugged problems, or otherwise helped with Robot Framework 7.0 860 | development. 861 | 862 | See you at `RoboCon 2024 `__ either onsite or online! 863 | 864 | | `Pekka Klärck`_ 865 | | Robot Framework lead developer 866 | 867 | Full list of fixes and enhancements 868 | =================================== 869 | 870 | .. list-table:: 871 | :header-rows: 1 872 | 873 | * - ID 874 | - Type 875 | - Priority 876 | - Summary 877 | * - `#3296`_ 878 | - enhancement 879 | - critical 880 | - Support keywords and control structures with listener version 3 881 | * - `#3761`_ 882 | - enhancement 883 | - critical 884 | - Native `VAR` syntax to create variables inside tests and keywords 885 | * - `#4294`_ 886 | - enhancement 887 | - critical 888 | - Drop Python 3.6 and 3.7 support 889 | * - `#4710`_ 890 | - enhancement 891 | - critical 892 | - Support library keywords with both embedded and normal arguments 893 | * - `#4847`_ 894 | - enhancement 895 | - critical 896 | - Support JSON serialization with result model 897 | * - `#4659`_ 898 | - bug 899 | - high 900 | - Performance regression when using `Run Keyword` and keyword name contains a variable 901 | * - `#4921`_ 902 | - bug 903 | - high 904 | - Log levels don't work correctly with `robot:flatten` 905 | * - `#3725`_ 906 | - enhancement 907 | - high 908 | - Support dark theme with report and log 909 | * - `#4258`_ 910 | - enhancement 911 | - high 912 | - Change timestamps from custom strings to `datetime` in result model and to ISO 8601 format in output.xml 913 | * - `#4374`_ 914 | - enhancement 915 | - high 916 | - Support removing tags set globally by using `-tag` syntax with `[Tags]` setting 917 | * - `#4633`_ 918 | - enhancement 919 | - high 920 | - Automatic argument conversion and validation for `Literal` 921 | * - `#4711`_ 922 | - enhancement 923 | - high 924 | - Support type aliases in formats `'list[int]'` and `'int | float'` in argument conversion 925 | * - `#4803`_ 926 | - enhancement 927 | - high 928 | - Async support to dynamic and hybrid library APIs 929 | * - `#4808`_ 930 | - bug 931 | - medium 932 | - Async keywords are not stopped when execution is stopped gracefully 933 | * - `#4859`_ 934 | - bug 935 | - medium 936 | - Parsing errors in reStructuredText files have no source 937 | * - `#4880`_ 938 | - bug 939 | - medium 940 | - Initially empty test fails even if pre-run modifier adds content to it 941 | * - `#4886`_ 942 | - bug 943 | - medium 944 | - `Set Variable If` is slow if it has several conditions 945 | * - `#4898`_ 946 | - bug 947 | - medium 948 | - Resolving special variables can fail with confusing message 949 | * - `#4915`_ 950 | - bug 951 | - medium 952 | - `cached_property` attributes are called when importing library 953 | * - `#4924`_ 954 | - bug 955 | - medium 956 | - WHILE `on_limit` missing from listener v2 attributes 957 | * - `#4926`_ 958 | - bug 959 | - medium 960 | - WHILE and TRY content are not removed with `--removekeywords all` 961 | * - `#4945`_ 962 | - bug 963 | - medium 964 | - `TypedDict` with forward references do not work in argument conversion 965 | * - `#4956`_ 966 | - bug 967 | - medium 968 | - DotDict behaves inconsistent on equality checks. `x == y` != `not x != y` and not `x != y` == `not x == y` 969 | * - `#4964`_ 970 | - bug 971 | - medium 972 | - Variables set using `Set Suite Variable` with `children=True` cannot be properly overwritten 973 | * - `#4980`_ 974 | - bug 975 | - medium 976 | - DateTime library uses deprecated `datetime.utcnow()` 977 | * - `#4999`_ 978 | - bug 979 | - medium 980 | - XML Library: Double namespace during Element To String 981 | * - `#5005`_ 982 | - bug 983 | - medium 984 | - `Log Variables` should not consume iterables 985 | * - `#3017`_ 986 | - enhancement 987 | - medium 988 | - Add return type to Libdoc specs and HTML output 989 | * - `#4103`_ 990 | - enhancement 991 | - medium 992 | - Process: Change the default `stdin` behavior from `subprocess.PIPE` to `None` 993 | * - `#4302`_ 994 | - enhancement 995 | - medium 996 | - Remove `Reserved` library 997 | * - `#4343`_ 998 | - enhancement 999 | - medium 1000 | - Collections: Support case-insensitive list and dictionary comparisons 1001 | * - `#4375`_ 1002 | - enhancement 1003 | - medium 1004 | - Change token type of `AS` (or `WITH NAME`) used with library imports to `Token.AS` 1005 | * - `#4385`_ 1006 | - enhancement 1007 | - medium 1008 | - Change the parsing model object produced by `Test Tags` (and `Force Tags`) to `TestTags` 1009 | * - `#4432`_ 1010 | - enhancement 1011 | - medium 1012 | - Loudly deprecate singular section headers 1013 | * - `#4501`_ 1014 | - enhancement 1015 | - medium 1016 | - Loudly deprecate old Python 2/3 compatibility layer and other deprecated utils 1017 | * - `#4524`_ 1018 | - enhancement 1019 | - medium 1020 | - Loudly deprecate variables used as embedded arguments not matching custom patterns 1021 | * - `#4545`_ 1022 | - enhancement 1023 | - medium 1024 | - Support creating assigned variable name based on another variable like `${${var}} = Keyword` 1025 | * - `#4667`_ 1026 | - enhancement 1027 | - medium 1028 | - Remove deprecated constructs from Libdoc spec files 1029 | * - `#4685`_ 1030 | - enhancement 1031 | - medium 1032 | - Deprecate `SHORTEST` mode being default with `FOR IN ZIP` loops 1033 | * - `#4708`_ 1034 | - enhancement 1035 | - medium 1036 | - Use `assing`, not `variable`, with FOR and TRY/EXCEPT model objects when referring to assigned variables 1037 | * - `#4720`_ 1038 | - enhancement 1039 | - medium 1040 | - Require `--suite parent.suite` to match the full suite name 1041 | * - `#4721`_ 1042 | - enhancement 1043 | - medium 1044 | - Change behavior of `--test` and `--include` so that they are cumulative 1045 | * - `#4747`_ 1046 | - enhancement 1047 | - medium 1048 | - Support `[Setup]` with user keywords 1049 | * - `#4784`_ 1050 | - enhancement 1051 | - medium 1052 | - Remote: Enhance `datetime`, `date` and `timedelta` conversion 1053 | * - `#4841`_ 1054 | - enhancement 1055 | - medium 1056 | - Add typing to all modules under `robot.api` 1057 | * - `#4846`_ 1058 | - enhancement 1059 | - medium 1060 | - Result model: Loudly deprecate not needed attributes and remove already deprecated ones 1061 | * - `#4872`_ 1062 | - enhancement 1063 | - medium 1064 | - Control continue-on-failure mode by using recursive and non-recursive tags together 1065 | * - `#4876`_ 1066 | - enhancement 1067 | - medium 1068 | - Loudly deprecate `[Return]` setting 1069 | * - `#4877`_ 1070 | - enhancement 1071 | - medium 1072 | - XML: Support ignoring element order with `Elements Should Be Equal` 1073 | * - `#4883`_ 1074 | - enhancement 1075 | - medium 1076 | - Result model: Add `message` to keywords and control structures and remove `doc` from controls 1077 | * - `#4884`_ 1078 | - enhancement 1079 | - medium 1080 | - Result model: Enhance storing keyword name 1081 | * - `#4896`_ 1082 | - enhancement 1083 | - medium 1084 | - Support `separator=` configuration option with scalar variables in Variables section 1085 | * - `#4903`_ 1086 | - enhancement 1087 | - medium 1088 | - Support argument conversion and named arguments with dynamic variable files 1089 | * - `#4905`_ 1090 | - enhancement 1091 | - medium 1092 | - Support creating variable name based on another variable like `${${VAR}}` in Variables section 1093 | * - `#4910`_ 1094 | - enhancement 1095 | - medium 1096 | - Make listener v3 the default listener API 1097 | * - `#4912`_ 1098 | - enhancement 1099 | - medium 1100 | - Parsing model: Move `type` and `tokens` from `_fields` to `_attributes` 1101 | * - `#4930`_ 1102 | - enhancement 1103 | - medium 1104 | - BuiltIn: New `Reset Log Level` keyword for resetting the log level to the original value 1105 | * - `#4939`_ 1106 | - enhancement 1107 | - medium 1108 | - Parsing model: Rename `Return` to `ReturnSetting` and `ReturnStatement` to `Return` 1109 | * - `#4942`_ 1110 | - enhancement 1111 | - medium 1112 | - Add public argument conversion API for libraries and other tools 1113 | * - `#4952`_ 1114 | - enhancement 1115 | - medium 1116 | - Collections: Make `ignore_order` and `ignore_keys` recursive 1117 | * - `#4960`_ 1118 | - enhancement 1119 | - medium 1120 | - Support integer conversion with strings representing whole number floats like `'1.0'` and `'2e10'` 1121 | * - `#4976`_ 1122 | - enhancement 1123 | - medium 1124 | - Support string `SELF` (case-insenstive) when library registers itself as listener 1125 | * - `#4979`_ 1126 | - enhancement 1127 | - medium 1128 | - Add `robot.result.TestSuite.to/from_xml` methods 1129 | * - `#4982`_ 1130 | - enhancement 1131 | - medium 1132 | - DateTime: Support `datetime.date` as an input format with date related keywords 1133 | * - `#4983`_ 1134 | - enhancement 1135 | - medium 1136 | - Type conversion: Remove support for deprecated `ByteString` 1137 | * - `#5000`_ 1138 | - enhancement 1139 | - medium 1140 | - Nicer API for setting keyword call arguments programmatically 1141 | * - `#4934`_ 1142 | - --- 1143 | - medium 1144 | - Enhance performance of visiting parsing model 1145 | * - `#4621`_ 1146 | - bug 1147 | - low 1148 | - OperatingSystem library docs have broken link / title 1149 | * - `#4798`_ 1150 | - bug 1151 | - low 1152 | - `--removekeywords passed` doesn't remove test setup and teardown 1153 | * - `#4867`_ 1154 | - bug 1155 | - low 1156 | - Original order of dictionaries is not preserved when they are pretty printed in log messages 1157 | * - `#4870`_ 1158 | - bug 1159 | - low 1160 | - User keyword teardown missing from running model JSON schema 1161 | * - `#4904`_ 1162 | - bug 1163 | - low 1164 | - Importing static variable file with arguments does not fail 1165 | * - `#4913`_ 1166 | - bug 1167 | - low 1168 | - Trace log level logs arguments twice for embedded arguments 1169 | * - `#4927`_ 1170 | - bug 1171 | - low 1172 | - WARN level missing from the log level selector in log.html 1173 | * - `#4967`_ 1174 | - bug 1175 | - low 1176 | - Variables are not resolved in keyword name in WUKS error message 1177 | * - `#4861`_ 1178 | - enhancement 1179 | - low 1180 | - Remove deprecated `accept_plain_values` from `timestr_to_secs` utility function 1181 | * - `#4862`_ 1182 | - enhancement 1183 | - low 1184 | - Deprecate `elapsed_time_to_string` accepting time as milliseconds 1185 | * - `#4864`_ 1186 | - enhancement 1187 | - low 1188 | - Process: Make warning about processes hanging if output buffers get full more visible 1189 | * - `#4885`_ 1190 | - enhancement 1191 | - low 1192 | - Add `full_name` to replace `longname` to suite and test objects 1193 | * - `#4900`_ 1194 | - enhancement 1195 | - low 1196 | - Make keywords and control structures in log look more like original data 1197 | * - `#4922`_ 1198 | - enhancement 1199 | - low 1200 | - Change the log level of `Set Log Level` message from INFO to DEBUG 1201 | * - `#4933`_ 1202 | - enhancement 1203 | - low 1204 | - Type conversion: Ignore hyphens when matching enum members 1205 | * - `#4935`_ 1206 | - enhancement 1207 | - low 1208 | - Use `casefold`, not `lower`, when comparing strings case-insensitively 1209 | * - `#4936`_ 1210 | - enhancement 1211 | - low 1212 | - Remove bytes support from `robot.utils.normalize` function 1213 | * - `#4954`_ 1214 | - enhancement 1215 | - low 1216 | - Collections and String: Add `ignore_case` as alias for `case_insensitive` 1217 | * - `#4958`_ 1218 | - enhancement 1219 | - low 1220 | - Document `robot_running` and `dry_run_active` properties of the BuiltIn library in the User Guide 1221 | * - `#4975`_ 1222 | - enhancement 1223 | - low 1224 | - Support `times` and `x` suffixes with `WHILE` limit to make it more compatible with `Wait Until Keyword Succeeds` 1225 | * - `#4988`_ 1226 | - enhancement 1227 | - low 1228 | - Change paths passed to listener v3 methods to `pathlib.Path` instances 1229 | 1230 | Altogether 88 issues. View on the `issue tracker `__. 1231 | 1232 | .. _#3296: https://github.com/robotframework/robotframework/issues/3296 1233 | .. _#3761: https://github.com/robotframework/robotframework/issues/3761 1234 | .. _#4294: https://github.com/robotframework/robotframework/issues/4294 1235 | .. _#4710: https://github.com/robotframework/robotframework/issues/4710 1236 | .. _#4847: https://github.com/robotframework/robotframework/issues/4847 1237 | .. _#4659: https://github.com/robotframework/robotframework/issues/4659 1238 | .. _#4921: https://github.com/robotframework/robotframework/issues/4921 1239 | .. _#3725: https://github.com/robotframework/robotframework/issues/3725 1240 | .. _#4258: https://github.com/robotframework/robotframework/issues/4258 1241 | .. _#4374: https://github.com/robotframework/robotframework/issues/4374 1242 | .. _#4633: https://github.com/robotframework/robotframework/issues/4633 1243 | .. _#4711: https://github.com/robotframework/robotframework/issues/4711 1244 | .. _#4803: https://github.com/robotframework/robotframework/issues/4803 1245 | .. _#4808: https://github.com/robotframework/robotframework/issues/4808 1246 | .. _#4859: https://github.com/robotframework/robotframework/issues/4859 1247 | .. _#4880: https://github.com/robotframework/robotframework/issues/4880 1248 | .. _#4886: https://github.com/robotframework/robotframework/issues/4886 1249 | .. _#4898: https://github.com/robotframework/robotframework/issues/4898 1250 | .. _#4915: https://github.com/robotframework/robotframework/issues/4915 1251 | .. _#4924: https://github.com/robotframework/robotframework/issues/4924 1252 | .. _#4926: https://github.com/robotframework/robotframework/issues/4926 1253 | .. _#4945: https://github.com/robotframework/robotframework/issues/4945 1254 | .. _#4956: https://github.com/robotframework/robotframework/issues/4956 1255 | .. _#4964: https://github.com/robotframework/robotframework/issues/4964 1256 | .. _#4980: https://github.com/robotframework/robotframework/issues/4980 1257 | .. _#4999: https://github.com/robotframework/robotframework/issues/4999 1258 | .. _#5005: https://github.com/robotframework/robotframework/issues/5005 1259 | .. _#3017: https://github.com/robotframework/robotframework/issues/3017 1260 | .. _#4103: https://github.com/robotframework/robotframework/issues/4103 1261 | .. _#4302: https://github.com/robotframework/robotframework/issues/4302 1262 | .. _#4343: https://github.com/robotframework/robotframework/issues/4343 1263 | .. _#4375: https://github.com/robotframework/robotframework/issues/4375 1264 | .. _#4385: https://github.com/robotframework/robotframework/issues/4385 1265 | .. _#4432: https://github.com/robotframework/robotframework/issues/4432 1266 | .. _#4501: https://github.com/robotframework/robotframework/issues/4501 1267 | .. _#4524: https://github.com/robotframework/robotframework/issues/4524 1268 | .. _#4545: https://github.com/robotframework/robotframework/issues/4545 1269 | .. _#4667: https://github.com/robotframework/robotframework/issues/4667 1270 | .. _#4685: https://github.com/robotframework/robotframework/issues/4685 1271 | .. _#4708: https://github.com/robotframework/robotframework/issues/4708 1272 | .. _#4720: https://github.com/robotframework/robotframework/issues/4720 1273 | .. _#4721: https://github.com/robotframework/robotframework/issues/4721 1274 | .. _#4747: https://github.com/robotframework/robotframework/issues/4747 1275 | .. _#4784: https://github.com/robotframework/robotframework/issues/4784 1276 | .. _#4841: https://github.com/robotframework/robotframework/issues/4841 1277 | .. _#4846: https://github.com/robotframework/robotframework/issues/4846 1278 | .. _#4872: https://github.com/robotframework/robotframework/issues/4872 1279 | .. _#4876: https://github.com/robotframework/robotframework/issues/4876 1280 | .. _#4877: https://github.com/robotframework/robotframework/issues/4877 1281 | .. _#4883: https://github.com/robotframework/robotframework/issues/4883 1282 | .. _#4884: https://github.com/robotframework/robotframework/issues/4884 1283 | .. _#4896: https://github.com/robotframework/robotframework/issues/4896 1284 | .. _#4903: https://github.com/robotframework/robotframework/issues/4903 1285 | .. _#4905: https://github.com/robotframework/robotframework/issues/4905 1286 | .. _#4910: https://github.com/robotframework/robotframework/issues/4910 1287 | .. _#4912: https://github.com/robotframework/robotframework/issues/4912 1288 | .. _#4930: https://github.com/robotframework/robotframework/issues/4930 1289 | .. _#4939: https://github.com/robotframework/robotframework/issues/4939 1290 | .. _#4942: https://github.com/robotframework/robotframework/issues/4942 1291 | .. _#4952: https://github.com/robotframework/robotframework/issues/4952 1292 | .. _#4960: https://github.com/robotframework/robotframework/issues/4960 1293 | .. _#4976: https://github.com/robotframework/robotframework/issues/4976 1294 | .. _#4979: https://github.com/robotframework/robotframework/issues/4979 1295 | .. _#4982: https://github.com/robotframework/robotframework/issues/4982 1296 | .. _#4983: https://github.com/robotframework/robotframework/issues/4983 1297 | .. _#5000: https://github.com/robotframework/robotframework/issues/5000 1298 | .. _#4934: https://github.com/robotframework/robotframework/issues/4934 1299 | .. _#4621: https://github.com/robotframework/robotframework/issues/4621 1300 | .. _#4798: https://github.com/robotframework/robotframework/issues/4798 1301 | .. _#4867: https://github.com/robotframework/robotframework/issues/4867 1302 | .. _#4870: https://github.com/robotframework/robotframework/issues/4870 1303 | .. _#4904: https://github.com/robotframework/robotframework/issues/4904 1304 | .. _#4913: https://github.com/robotframework/robotframework/issues/4913 1305 | .. _#4927: https://github.com/robotframework/robotframework/issues/4927 1306 | .. _#4967: https://github.com/robotframework/robotframework/issues/4967 1307 | .. _#4861: https://github.com/robotframework/robotframework/issues/4861 1308 | .. _#4862: https://github.com/robotframework/robotframework/issues/4862 1309 | .. _#4864: https://github.com/robotframework/robotframework/issues/4864 1310 | .. _#4885: https://github.com/robotframework/robotframework/issues/4885 1311 | .. _#4900: https://github.com/robotframework/robotframework/issues/4900 1312 | .. _#4922: https://github.com/robotframework/robotframework/issues/4922 1313 | .. _#4933: https://github.com/robotframework/robotframework/issues/4933 1314 | .. _#4935: https://github.com/robotframework/robotframework/issues/4935 1315 | .. _#4936: https://github.com/robotframework/robotframework/issues/4936 1316 | .. _#4954: https://github.com/robotframework/robotframework/issues/4954 1317 | .. _#4958: https://github.com/robotframework/robotframework/issues/4958 1318 | .. _#4975: https://github.com/robotframework/robotframework/issues/4975 1319 | .. _#4988: https://github.com/robotframework/robotframework/issues/4988 1320 | -------------------------------------------------------------------------------- /test/markups/README.markdown: -------------------------------------------------------------------------------- 1 | * One 2 | * Two 3 | -------------------------------------------------------------------------------- /test/markups/README.markdown.html: -------------------------------------------------------------------------------- 1 |
    2 |
  • One
    • 3 |
  • Two
    • 4 |
-------------------------------------------------------------------------------- /test/markups/README.mediawiki: -------------------------------------------------------------------------------- 1 | [[Home|» JRuby Project Wiki Home Page]] 2 |

Embedding JRuby

3 | Using Java from Ruby is JRuby's best-known feature---but you can also go in the other direction, and use Ruby from Java. There are several different ways to do this. You can execute entire Ruby scripts, call individual Ruby methods, or even implement a Java interface in Ruby (thus allowing you to treat Ruby objects like Java ones). We refer to all these techniques generically as "embedding." This section will explain how to embed JRuby in your Java project. 4 | 5 | __TOC__ 6 | 7 | = Red Bridge (JRuby Embed) = 8 | 9 | one- 10 | 
a-b
11 | 12 | JRuby has long had a private embedding API, which was closely tied to the runtime's internals and therefore changed frequently as JRuby evolved. Since version 1.4, however, we have also provided a more stable public API, known as Red Bridge or JRuby Embed. Existing Java programs written to the [[DirectJRubyEmbedding|legacy API]] should still work, but we strongly recommend Red Bridge for all new projects. 13 | 14 | == Features of Red Bridge == 15 | Red Bridge consists of two layers: Embed Core on the bottom, and implementations of [http://www.jcp.org/en/jsr/detail?id=223 JSR223] and [http://jakarta.apache.org/bsf/ BSF] on top. Embed Core is JRuby-specific, and can take advantage of much of JRuby's power. JSR223 and BSF are more general interfaces that provide a common ground across scripting languages. 16 | 17 | Which API should you use? For projects where Ruby is the only scripting language involved, we recommend Embed Core for the following reasons: 18 | 19 | # With Embed Core, you can create several Ruby environments in one JVM, and configure them individually (via org.jruby.RubyInstanceConfig. With the other APIs, configuration options can only be set globally, via the System properties. 20 | # Embed Core offers several shortcuts, such as loading scripts from a java.io.InputStream, or returning Java-friendly objects from Ruby code. These allow you to skip a lot of boilerplate. 21 | 22 | For projects requiring multiple scripting languages, JSR223 is a good fit. Though the API is language-independent, JRuby's implementation of it allows you to set some Ruby-specific options. In particular, you can control the threading model of the scripting engine, the lifetime of local variables, compilation mode, and how line numbers are displayed. 23 | 24 | The full [http://jruby-embed.kenai.com/docs/ API documentation] has all the gory details. It's worth talking about a couple of the finer points here. 25 | 26 | = Previous Embedding JRuby Page= 27 | We recommend using Embed Core; however, if you're maintaining code that uses the old API, you can find its documentation on the [[JavaIntegration|legacy embedding]]This link goes nowhere. page. 28 | 29 | = References = 30 | 31 | -------------------------------------------------------------------------------- /test/markups/README.mediawiki.html: -------------------------------------------------------------------------------- 1 |

» JRuby Project Wiki Home Page 2 |

Embedding JRuby

3 | Using Java from Ruby is JRuby's best-known feature---but you can also go in the other direction, and use Ruby from Java. There are several different ways to do this. You can execute entire Ruby scripts, call individual Ruby methods, or even implement a Java interface in Ruby (thus allowing you to treat Ruby objects like Java ones). We refer to all these techniques generically as "embedding." This section will explain how to embed JRuby in your Java project. 4 | 5 |

6 |

Table of Contents

7 | 14 |
15 | 16 | 17 |

18 | Red Bridge (JRuby Embed) 19 |

20 | 21 | 22 | 23 |

one-<two 24 | 

a-b
25 | 26 |

JRuby has long had a private embedding API, which was closely tied to the runtime's internals and therefore changed frequently as JRuby evolved. Since version 1.4, however, we have also provided a more stable public API, known as Red Bridge or JRuby Embed. Existing Java programs written to the legacy API should still work, but we strongly recommend Red Bridge for all new projects. 27 |

28 | 29 |

30 | Features of Red Bridge 31 |

32 | 33 | 34 |

Red Bridge consists of two layers: Embed Core on the bottom, and implementations of JSR223 and BSF on top. Embed Core is JRuby-specific, and can take advantage of much of JRuby's power. JSR223 and BSF are more general interfaces that provide a common ground across scripting languages. 35 |

36 |

Which API should you use? For projects where Ruby is the only scripting language involved, we recommend Embed Core for the following reasons: 37 |

38 | 39 | 40 | 41 |

    42 |
  1. With Embed Core, you can create several Ruby environments in one JVM, and configure them individually (via org.jruby.RubyInstanceConfig. With the other APIs, configuration options can only be set globally, via the System properties.
    2. 43 |
  2. Embed Core offers several shortcuts, such as loading scripts from a java.io.InputStream, or returning Java-friendly objects from Ruby code. These allow you to skip a lot of boilerplate.
    3. 44 |
45 | For projects requiring multiple scripting languages, JSR223 is a good fit. Though the API is language-independent, JRuby's implementation of it allows you to set some Ruby-specific options. In particular, you can control the threading model of the scripting engine, the lifetime of local variables, compilation mode, and how line numbers are displayed. 46 | 47 |

The full API documentation has all the gory details. It's worth talking about a couple of the finer points here. 48 |

49 | 50 |

51 | Previous Embedding JRuby Page 52 |

53 | 54 | 55 |

We recommend using Embed Core; however, if you're maintaining code that uses the old API, you can find its documentation on the legacy embedding[1] page. 56 |

57 | 58 |

59 | References 60 |

61 | 62 | 63 |

  1. 64 | ^ This link goes nowhere.
-------------------------------------------------------------------------------- /test/markups/README.noformat: -------------------------------------------------------------------------------- 1 | * One 2 | * Two 3 | -------------------------------------------------------------------------------- /test/markups/README.noformat.html: -------------------------------------------------------------------------------- 1 | * One 2 | * Two -------------------------------------------------------------------------------- /test/markups/README.org: -------------------------------------------------------------------------------- 1 | #+TITLE: org-ruby 2 | #+AUTHOR: Brian Dewey 3 | #+EMAIL: bdewey@gmail.com 4 | #+DATE: 2009-12-21 5 | #+DESCRIPTION: 6 | #+KEYWORDS: 7 | #+LANGUAGE: en 8 | #+OPTIONS: H:3 num:t toc:nil \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t 9 | #+OPTIONS: TeX:t LaTeX:nil skip:nil d:nil todo:nil pri:nil tags:not-in-toc 10 | #+EXPORT_EXCLUDE_TAGS: exclude 11 | #+STARTUP: showall 12 | 13 | | Status: | Under Development | 14 | | Location: | [[http://github.com/wallyqs/org-ruby]] | 15 | | Version: | 0.9.0 | 16 | 17 | * Description 18 | 19 | Helpful Ruby routines for parsing orgmode files. The most 20 | significant thing this library does today is convert orgmode files 21 | to textile. Currently, you cannot do much to customize the 22 | conversion. The supplied textile conversion is optimized for 23 | extracting "content" from the orgfile as opposed to "metadata." 24 | 25 | * History 26 | 27 | ** 2014-02-08: Version 0.9.0 28 | 29 | - Let's make sure =#+INCLUDE:= is not supported 30 | 31 | #+INCLUDE: "./README.txt" src text 32 | 33 | - And confirm that syntax highlight is supported 34 | 35 | #+begin_src ruby 36 | module GitHub 37 | module Markup 38 | VERSION = 'test' 39 | Version = VERSION 40 | end 41 | end 42 | #+end_src 43 | 44 | ** 2009-12-30: Version 0.5.1 45 | 46 | - Minor enhancement: Recognize lines starting with ":" as examples. 47 | - Minor enhancement: Recognize #+BEGIN_SRC as source blocks 48 | - Minor enhancement: Add "src" and "example" classes to 
 blocks.
 49 | 
 50 | 
 51 | ** 2009-12-30: Version 0.5.0
 52 | 
 53 |    - Parse (but not necessarily *use*) in-buffer settings. The following
 54 |      in-buffer settings *are* used:
 55 |      - Understand the #+TITLE: directive.
 56 |      - Exporting todo keywords (option todo:t)
 57 |      - Numbering headlines (option num:t)
 58 |      - Skipping text before the first headline (option skip:t)
 59 |      - Skipping tables (option |:nil)
 60 |      - Custom todo keywords
 61 |      - EXPORT_SELECT_TAGS and EXPORT_EXCLUDE_TAGS for controlling parts of
 62 |        the tree to export
 63 |    - Rewrite "file:(blah).org" links to "http:(blah).html" links. This
 64 |      makes the inter-links to other org-mode files work.
 65 |    - Uses  tags inside table rows that precede table separators.
 66 |    - Bugfixes:
 67 |      - Headings now have HTML escaped.
 68 | 
 69 | ** 2009-12-29: Version 0.4.2
 70 | 
 71 |    - Got rid of the extraneous newline at the start of code blocks.
 72 |    - Everything now shows up in code blocks, even org-mode metadata.
 73 |    - Fixed bugs:
 74 |      - Regressed smart double quotes with HTML escaping. Added a test
 75 |        case and fixed the regression.
 76 | 
 77 | ** 2009-12-29: Version 0.4.1
 78 |    - HTML is now escaped by default
 79 |    - org-mode comments will show up in a code block.
 80 | 
 81 | ** 2009-12-29: Version 0.4
 82 | 
 83 |    - The first thing output in HTML gets the class "title"
 84 |    - HTML output is now indented
 85 |    - Proper support for multi-paragraph list items.
 86 | 
 87 |      See? This paragraph is part of the last bullet.
 88 |      
 89 |    - Fixed bugs:
 90 |      - "rake spec" wouldn't work on Linux. Needed "require 'rubygems'".
 91 | 
 92 | ** 2009-12-27: Version 0.3
 93 | 
 94 |    - Uses rubypants to get better typography (smart quotes, ellipses, etc...).
 95 |    - Fixed bugs:
 96 |      - Tables and lists did not get properly closed at the end of file
 97 |      - You couldn't do inline formatting inside table cells
 98 |      - Characters in PRE blocks were not HTML escaped.
 99 |    
100 | ** 2009-12-26: Version 0.2
101 | 
102 |    - Added =to_html= output on the parser.
103 |    - Added support for the full range of inline markup: *bold*,
104 |      /italic/, =code=, ~verbatim~, _underline_, +strikethrough+.
105 |    - Lots of refactoring to make the code more maintainable.
106 | 
107 | ** 2009-12-23: Version 0.1
108 | 
109 |    - Added support for block code, like this:
110 | 
111 |      #+BEGIN_EXAMPLE
112 |      def flush!
113 |      @logger.debug "FLUSH ==========> #{@output_type}"
114 |      if (@output_type == :blank) then
115 |        @output << "\n"
116 |      elsif (@buffer.length > 0) then
117 |        if @cancel_modifier then
118 |          @output << "p. " if @output_type == :paragraph
119 |          @cancel_modifier = false
120 |        end
121 |        @output << @paragraph_modifier if (@paragraph_modifier and not sticky_modifier?)
122 |        @output << @buffer.textile_substitution << "\n"
123 |      end
124 |      @buffer = ""
125 |    end
126 |    #+END_EXAMPLE
127 | 
128 |    - Major code cleanup: Created the =OutputBuffer= class that
129 |      greatly simplified a lot of the messiness of =textile=
130 |      conversion.
131 |    - Added support for line breaks within list items.
132 | 


--------------------------------------------------------------------------------
/test/markups/README.org.html:
--------------------------------------------------------------------------------
  1 | 
org-ruby

  2 | 
  3 |   
  4 | 
  5 | 
  6 | 
  7 |   
  8 | 
  9 | 
 10 | 
 11 |   
 12 | 
 13 | 
 14 | 
 15 | 
Status:Under Development
Location:http://github.com/wallyqs/org-ruby
Version:0.9.0

 16 | 
1 Description

 17 | 
Helpful Ruby routines for parsing orgmode files. The most
 18 |   significant thing this library does today is convert orgmode files
 19 |   to textile. Currently, you cannot do much to customize the
 20 |   conversion. The supplied textile conversion is optimized for
 21 |   extracting “content” from the orgfile as opposed to “metadata.”

 22 | 
2 History

 23 | 
2.1 2014-02-08: Version 0.9.0

 24 | 
    
 25 |   
  • Let’s make sure #+INCLUDE: is not supported
    • 
 26 | 

 27 | 
    
 28 |   
  • And confirm that syntax highlight is supported
    • 
 29 | 

 30 | 
 31 | module GitHub
 32 |   module Markup
 33 |     VERSION = 'test'
 34 |     Version = VERSION
 35 |   end
 36 | end
 37 | 

 38 | 
2.2 2009-12-30: Version 0.5.1

 39 | 
    
 40 |   
  • Minor enhancement: Recognize lines starting with “:” as examples.
    • 
 41 |   
  • Minor enhancement: Recognize #+BEGIN_SRC as source blocks
    • 
 42 |   
  • Minor enhancement: Add “src” and “example” classes to <pre> blocks.
    • 
 43 | 

 44 | 
2.3 2009-12-30: Version 0.5.0

 45 | 
    
 46 |   
  • Parse (but not necessarily use) in-buffer settings. The following
 47 |     in-buffer settings are used:
 48 |     
      
 49 |       
    • Understand the #+TITLE: directive.
      • 
 50 |       
    • Exporting todo keywords (option todo:t)
      • 
 51 |       
    • Numbering headlines (option num:t)
      • 
 52 |       
    • Skipping text before the first headline (option skip:t)
      • 
 53 |       
    • Skipping tables (option |:nil)
      • 
 54 |       
    • Custom todo keywords
      • 
 55 |       
    • EXPORT_SELECT_TAGS and EXPORT_EXCLUDE_TAGS for controlling parts of
 56 |         the tree to export
      • 
 57 |     
    
 58 |   
    • 
 59 |   
  • Rewrite “file:(blah).org” links to “http:(blah).html” links. This
 60 |     makes the inter-links to other org-mode files work.
    • 
 61 |   
  • Uses <th> tags inside table rows that precede table separators.
    • 
 62 |   
  • Bugfixes:
 63 |     
      
 64 |       
    • Headings now have HTML escaped.
      • 
 65 |     
    
 66 |   
    • 
 67 | 

 68 | 
2.4 2009-12-29: Version 0.4.2

 69 | 
    
 70 |   
  • Got rid of the extraneous newline at the start of code blocks.
    • 
 71 |   
  • Everything now shows up in code blocks, even org-mode metadata.
    • 
 72 |   
  • Fixed bugs:
 73 |     
      
 74 |       
    • Regressed smart double quotes with HTML escaping. Added a test
 75 |         case and fixed the regression.
      • 
 76 |     
    
 77 |   
    • 
 78 | 

 79 | 
2.5 2009-12-29: Version 0.4.1

 80 | 
    
 81 |   
  • HTML is now escaped by default
    • 
 82 |   
  • org-mode comments will show up in a code block.
    • 
 83 | 

 84 | 
2.6 2009-12-29: Version 0.4

 85 | 
    
 86 |   
  • The first thing output in HTML gets the class “title”
    • 
 87 |   
  • HTML output is now indented
    • 
 88 |   
  • Proper support for multi-paragraph list items.
 89 |     
    See? This paragraph is part of the last bullet.
    
 90 |   
    • 
 91 |   
  • Fixed bugs:
 92 |     
      
 93 |       
    • “rake spec” wouldn’t work on Linux. Needed “require ‘rubygems’”.
      • 
 94 |     
    
 95 |   
    • 
 96 | 

 97 | 
2.7 2009-12-27: Version 0.3

 98 | 
    
 99 |   
  • Uses rubypants to get better typography (smart quotes, ellipses, etc…).
    • 
100 |   
  • Fixed bugs:
101 |     
      
102 |       
    • Tables and lists did not get properly closed at the end of file
      • 
103 |       
    • You couldn’t do inline formatting inside table cells
      • 
104 |       
    • Characters in PRE blocks were not HTML escaped.
      • 
105 |     
    
106 |   
    • 
107 | 

108 | 
2.8 2009-12-26: Version 0.2

109 | 
    
110 |   
  • Added to_html output on the parser.
    • 
111 |   
  • Added support for the full range of inline markup: bold,
112 |     italic, code, verbatim, underline, strikethrough.
    • 
113 |   
  • Lots of refactoring to make the code more maintainable.
    • 
114 | 

115 | 
2.9 2009-12-23: Version 0.1

116 | 
    
117 |   
  • Added support for block code, like this:
118 |     
    119 |   def flush!
120 |   @logger.debug "FLUSH ==========> #{@output_type}"
121 |   if (@output_type == :blank) then
122 |     @output << "\n"
123 |   elsif (@buffer.length > 0) then
124 |     if @cancel_modifier then
125 |       @output << "p. " if @output_type == :paragraph
126 |       @cancel_modifier = false
127 |     end
128 |     @output << @paragraph_modifier if (@paragraph_modifier and not sticky_modifier?)
129 |     @output << @buffer.textile_substitution << "\n"
130 |   end
131 |   @buffer = ""
132 | end
133 |     
    
134 |   
    • 
135 |   
  • Major code cleanup: Created the OutputBuffer class that
136 |     greatly simplified a lot of the messiness of textile
137 |     conversion.
    • 
138 |   
  • Added support for line breaks within list items.
    • 
139 | 



--------------------------------------------------------------------------------
/test/markups/README.pod:
--------------------------------------------------------------------------------
 1 | =head1 Matrixy
 2 | 
 3 | =head2 INTRODUCTION
 4 | 
 5 | This is a port of the MATLAB/Octave programming language to Parrot. See the
 6 | ROADMAP file for more information on the status of this project, and what else
 7 | needs to be done.
 8 | 
 9 | =head2 ABOUT
10 | 
11 | Primary goals are:
12 | 
13 | =over 4
14 | 
15 | =item * Create a working compiler that understands the majority of the
16 | MATLAB/Octave programming language.
17 | 
18 | =back
19 | 
20 | =head2 IMPLEMENTATION
21 | 
22 | This project is broken into three primary components:
23 | 
24 | =over 4
25 | 
26 | =item * The first is the parser, located in the C directory. The
27 | parser proper is composed of three source files, F which is a
28 | Perl6Grammar file, and F which is the associated actions file
29 | written in NQP, and F which is the operator precedence parser.
30 | In addition, several helper functions used by the parser are located in
31 | C.
32 | 
33 | =item * The second component is the library of builtin functions in the
34 | C directory. These functions are, currently, written primarily in
35 | PIR. Function names prefixed with an underscore are "private" functions for use
36 | with the parser. Other functions should have names which are the same as names
37 | for regular MATLAB or Octave functions, since they will be available to the
38 | HLL. These are also separated into different namespaces depending on visibility
39 | and utility.
40 | 
41 | =item * A number of library functions are written in M, or mostly M with some
42 | inline PIR code in C.
43 | 
44 | =back
45 | 
46 | =head2 DEPENDENCIES
47 | 
48 | Matrixy depends on these dependencies:
49 | 
50 | =head3 Parrot
51 | 
52 | To get a proper version of Parrot to build Matrixy, you will need to check out
53 | and build Parrot from source:
54 | 
55 |     svn co http://svn.parrot.org/parrot/trunk parrot
56 |     cd parrot
57 |     perl Configure.pl
58 |     make && make test && make install-dev
59 | 
60 | =head3 Parrot-Linear-Algebra
61 | 
62 | The linear algebra package for Parrot is available separately and provides
63 | functionality required by Matrixy. This includes matrix data types and matrix
64 | manipulation libraries
65 | 
66 | =head2 BUILDING
67 | 
68 | Once all dependencies are in place, you can build Matrixy using this sequence of
69 | commands:
70 | 
71 |     perl Configure.pl
72 |     nmake test
73 | 
74 | =head2 TODO
75 | 
76 |     * Parser
77 |     * Standard Builtins
78 |     * Test against Octave Test Suite.
79 | 
80 | =head2 BUGS
81 | 
82 | Lots!
83 | 
84 | =head2 CONTACT
85 | 
86 | If you need to contact the Matrixy team, go to the project home page at:
87 | 
88 | www.github.com\Whiteknight\matrixy
89 | 
90 | 


--------------------------------------------------------------------------------
/test/markups/README.pod.html:
--------------------------------------------------------------------------------
 1 | 
Matrixy

 2 | 
 3 | 
INTRODUCTION

 4 | 
 5 | 
This is a port of the MATLAB/Octave programming language to Parrot. See the ROADMAP file for more information on the status of this project, and what else needs to be done.

 6 | 
 7 | 
ABOUT

 8 | 
 9 | 
Primary goals are:

10 | 
11 | 
    
12 | 
13 | 
  • 
14 | 
    Create a working compiler that understands the majority of the MATLAB/Octave programming language.
    
15 | 
16 | 
    • 
17 | 

18 | 
19 | 
IMPLEMENTATION

20 | 
21 | 
This project is broken into three primary components:

22 | 
23 | 
    
24 | 
25 | 
  • 
26 | 
    The first is the parser, located in the src/parser/ directory. The parser proper is composed of three source files, grammar.pg which is a Perl6Grammar file, and actions.pm which is the associated actions file written in NQP, and grammar-oper.pm which is the operator precedence parser. In addition, several helper functions used by the parser are located in src/internals.
    
27 | 
28 | 
    • 
29 | 
  • 
30 | 
    The second component is the library of builtin functions in the src/builtins/ directory. These functions are, currently, written primarily in PIR. Function names prefixed with an underscore are "private" functions for use with the parser. Other functions should have names which are the same as names for regular MATLAB or Octave functions, since they will be available to the HLL. These are also separated into different namespaces depending on visibility and utility.
    
31 | 
32 | 
    • 
33 | 
  • 
34 | 
    A number of library functions are written in M, or mostly M with some inline PIR code in toolbox/.
    
35 | 
36 | 
    • 
37 | 

38 | 
39 | 
DEPENDENCIES

40 | 
41 | 
Matrixy depends on these dependencies:

42 | 
43 | 
Parrot

44 | 
45 | 
To get a proper version of Parrot to build Matrixy, you will need to check out and build Parrot from source:

46 | 
47 | 
svn co http://svn.parrot.org/parrot/trunk parrot
48 | cd parrot
49 | perl Configure.pl
50 | make && make test && make install-dev

51 | 
52 | 
Parrot-Linear-Algebra

53 | 
54 | 
The linear algebra package for Parrot is available separately and provides functionality required by Matrixy. This includes matrix data types and matrix manipulation libraries

55 | 
56 | 
BUILDING

57 | 
58 | 
Once all dependencies are in place, you can build Matrixy using this sequence of commands:

59 | 
60 | 
perl Configure.pl
61 | nmake test

62 | 
63 | 
TODO

64 | 
65 | 
* Parser
66 | * Standard Builtins
67 | * Test against Octave Test Suite.

68 | 
69 | 
BUGS

70 | 
71 | 
Lots!

72 | 
73 | 
CONTACT

74 | 
75 | 
If you need to contact the Matrixy team, go to the project home page at:

76 | 
77 | 
www.github.com\Whiteknight\matrixy



--------------------------------------------------------------------------------
/test/markups/README.rdoc:
--------------------------------------------------------------------------------
1 | * One
2 | * Two
3 | 
4 | This is an {absolute link}[http://github.com].  So is this: http://github.com
5 | 
6 | This is a {relative link}[link:rawr.html].  So is this: link:rawr.html


--------------------------------------------------------------------------------
/test/markups/README.rdoc.html:
--------------------------------------------------------------------------------
 1 | 
    
 2 | 
  • 
 3 | 
    One
    
 4 | 
    • 
 5 | 
  • 
 6 | 
    Two
    
 7 | 
    • 
 8 | 

 9 | 
10 | 
This is an absolute link.  So is this: github.com

11 | 
12 | 
This is a relative link.  So is this: rawr.html



--------------------------------------------------------------------------------
/test/markups/README.rst:
--------------------------------------------------------------------------------
 1 | Header 1
 2 | ========
 3 | --------
 4 | Subtitle
 5 | --------
 6 | 
 7 | Example text.
 8 | 
 9 | .. contents:: Table of Contents
10 | 
11 | .. _label_for_header_2:
12 | 
13 | Header 2
14 | --------
15 | 
16 | 1. Blah blah ``code`` blah
17 | 
18 | 2. More ``code``, hooray
19 | 
20 | 3. Somé UTF-8°
21 | 
22 | 4. `Link to the above header `_
23 | 
24 | The UTF-8 quote character in this table used to cause python to go boom. Now docutils just silently ignores it.
25 | 
26 | .. csv-table:: Things that are Awesome (on a scale of 1-11)
27 | 	:quote: ”
28 | 
29 | 	Thing,Awesomeness
30 | 	Icecream, 7
31 | 	Honey Badgers, 10.5
32 | 	Nickelback, -2
33 | 	Iron Man, 10
34 | 	Iron Man 2, 3
35 | 	Tabular Data, 5
36 | 	Made up ratings, 11
37 | 
38 | .. code::
39 | 
40 | 	A block of code
41 | 
42 | .. code:: python
43 | 
44 | 	python.code('hooray')
45 | 
46 | .. code:: python
47 | 	:caption: An ignored Sphinx option
48 | 	:made-up-option: An ignored made up option
49 | 
50 | 	python.code('hello world')
51 | 
52 | .. doctest:: ignored
53 | 
54 | 	>>> some_function()
55 | 	'result'
56 | 
57 | >>> some_function()
58 | 'result'
59 | 
60 | ==============  ==========================================================
61 | Travis          http://travis-ci.org/tony/pullv
62 | Docs            http://pullv.rtfd.org
63 | API             http://pullv.readthedocs.org/en/latest/api.html
64 | Issues          https://github.com/tony/pullv/issues
65 | Source          https://github.com/tony/pullv
66 | ==============  ==========================================================
67 | 
68 | 
69 | .. image:: https://scan.coverity.com/projects/621/badge.svg
70 | 	:target: https://scan.coverity.com/projects/621
71 | 	:alt: Coverity Scan Build Status
72 | 
73 | .. image:: https://scan.coverity.com/projects/621/badge.svg
74 | 	:alt: Coverity Scan Build Status
75 | 
76 | Field list
77 | ----------
78 | 
79 | :123456789 123456789 123456789 123456789 123456789 1: Uh-oh! This name is too long!
80 | :123456789 123456789 123456789 123456789 1234567890: this is a long name,
81 | 	but no problem!
82 | :123456789 12345: this is not so long, but long enough for the default!
83 | :123456789 1234: this should work even with the default :)
84 | 
85 | someone@somewhere.org
86 | 
87 | Press :kbd:`Ctrl+C` to quit
88 | 
89 | 
90 | .. raw:: html
91 | 
92 |     
RAW HTML!

93 | 


--------------------------------------------------------------------------------
/test/markups/README.rst.html:
--------------------------------------------------------------------------------
  1 | 
Header 1

  2 | 
Subtitle

  3 | 
Example text.

  4 | 

  5 | 
Table of Contents

  6 | 
 10 | 

 11 | 
 12 | 
 13 | 
Header 2

 14 | 
    
 15 | 
  1. Blah blah code blah
    2. 
 16 | 
  2. More code, hooray
    3. 
 17 | 
  3. Somé UTF-8°
    4. 
 18 | 
  4. Link to the above header
    5. 
 19 | 

 20 | 
The UTF-8 quote character in this table used to cause python to go boom. Now docutils just silently ignores it.

 21 | 
 22 | Things that are Awesome (on a scale of 1-11)
 23 | 
 24 | 
 25 | 
 26 | 
 27 | 
 28 | 
 29 | 
 30 | 
 31 | 
 32 | 
 33 | 
 34 | 
 35 | 
 36 | 
 37 | 
 38 | 
 39 | 
 40 | 
 41 | 
 42 | 
 43 | 
 44 | 
 45 | 
 46 | 
 47 | 
 48 | 
 49 | 
 50 | 
 51 | 
 52 | 
 53 | 
 54 | 
 55 | 
 56 | 
 57 | 
 58 | 
 59 | 
 60 | 
 61 | 
ThingAwesomeness
Icecream7
Honey Badgers10.5
Nickelback-2
Iron Man10
Iron Man 23
Tabular Data5
Made up ratings11

 62 | 
 63 | A block of code
 64 | 

 65 | 
 66 | python.code('hooray')
 67 | 

 68 | 
 69 | python.code('hello world')
 70 | 

 71 | 
 72 | >>> some_function()
 73 | 'result'
 74 | 

 75 | 
 76 | >>> some_function()
 77 | 'result'
 78 | 

 79 | 
 80 | 
 81 | 
 82 | 
 83 | 
 84 | 
 85 | 
 86 | 
 87 | 
 88 | 
 89 | 
 90 | 
 91 | 
 92 | 
 93 | 
 94 | 
 95 | 
 96 | 
 97 | 
 98 | 
 99 | 
100 | 
101 | 
102 | 
103 | 
104 | 
105 | 
106 | 
Travishttp://travis-ci.org/tony/pullv
Docshttp://pullv.rtfd.org
APIhttp://pullv.readthedocs.org/en/latest/api.html
Issueshttps://github.com/tony/pullv/issues
Sourcehttps://github.com/tony/pullv

107 | 
108 | Coverity Scan Build Status
109 | 
110 | Coverity Scan Build Status
111 | 
112 | 
Field list

113 | 
114 | 
115 | 
116 | 
117 | 
118 | 
119 | 
120 | 
121 | 
122 | 
123 | 
124 | 
126 | 
127 | 
128 | 
129 | 
130 | 
131 | 
132 | 
133 | 
134 | 
135 | 
136 | 
123456789 123456789 123456789 123456789 123456789 1:
 Uh-oh! This name is too long!
123456789 123456789 123456789 123456789 1234567890:this is a long name,
125 | but no problem!
123456789 12345:this is not so long, but long enough for the default!
123456789 1234:this should work even with the default :)

137 | 
someone@somewhere.org

138 | 
Press Ctrl+C to quit

139 | 
RAW HTML!
 p {color:blue;} 


--------------------------------------------------------------------------------
/test/markups/README.rst.txt:
--------------------------------------------------------------------------------
 1 | Header 1
 2 | ========
 3 | 
 4 | Example text.
 5 | 
 6 | Header 2
 7 | --------
 8 | 
 9 | 1. Blah blah ``code`` blah
10 | 
11 | 2. More ``code``, hooray
12 | 
13 | 3. Somé UTF-8°
14 | 
15 | ==============  ==========================================================
16 | Travis          http://travis-ci.org/tony/pullv
17 | Docs            http://pullv.rtfd.org
18 | API             http://pullv.readthedocs.org/en/latest/api.html
19 | Issues          https://github.com/tony/pullv/issues
20 | Source          https://github.com/tony/pullv
21 | ==============  ==========================================================
22 | 


--------------------------------------------------------------------------------
/test/markups/README.rst.txt.html:
--------------------------------------------------------------------------------
 1 | 
Header 1

 2 | 
Example text.

 3 | 
 4 | 
Header 2

 5 | 
    
 6 | 
  1. Blah blah code blah
    2. 
 7 | 
  2. More code, hooray
    3. 
 8 | 
  3. Somé UTF-8°
    4. 
 9 | 

10 | 
11 | 
12 | 
13 | 
14 | 
15 | 
16 | 
17 | 
18 | 
19 | 
20 | 
21 | 
22 | 
23 | 
24 | 
25 | 
26 | 
27 | 
28 | 
29 | 
30 | 
31 | 
32 | 
33 | 
34 | 
35 | 
36 | 
37 | 
Travishttp://travis-ci.org/tony/pullv
Docshttp://pullv.rtfd.org
APIhttp://pullv.readthedocs.org/en/latest/api.html
Issueshttps://github.com/tony/pullv/issues
Sourcehttps://github.com/tony/pullv



--------------------------------------------------------------------------------
/test/markups/README.textile:
--------------------------------------------------------------------------------
1 | * One
2 | * Two
3 | 


--------------------------------------------------------------------------------
/test/markups/README.textile.html:
--------------------------------------------------------------------------------
1 | 
    
2 | 	
  • One
    • 
3 | 	
  • Two
    • 
4 | 



--------------------------------------------------------------------------------
/test/markups/README.toc.asciidoc:
--------------------------------------------------------------------------------
 1 | = Document Title
 2 | :toc:
 3 | :toc-title: Contents
 4 | 
 5 | == Section A
 6 | 
 7 | === Subsection A-1
 8 | 
 9 | === Subsection A-2
10 | 
11 | == Section B
12 | 
13 | === Subsection B-1
14 | 
15 | === Subsection B-2
16 | 


--------------------------------------------------------------------------------
/test/markups/README.toc.asciidoc.html:
--------------------------------------------------------------------------------
 1 | 
Document Title

 2 | 

 3 | 
Contents

 4 | 
20 | 

21 | 

22 | 
Section A

23 | 

24 | 

25 | 
Subsection A-1

26 | 
27 | 

28 | 

29 | 
Subsection A-2

30 | 
31 | 

32 | 

33 | 

34 | 

35 | 
Section B

36 | 

37 | 

38 | 
Subsection B-1

39 | 
40 | 

41 | 

42 | 
Subsection B-2

43 | 
44 | 

45 | 

46 | 



--------------------------------------------------------------------------------
/test/markups/README.toc.rst:
--------------------------------------------------------------------------------
 1 | .. contents::
 2 |     :backlinks: none
 3 | 
 4 | .. sectnum::
 5 | 
 6 | Introduction
 7 | ============
 8 | 
 9 | What is pycparser?
10 | ------------------
11 | 
12 | **pycparser** is a parser for the C language, written in pure Python. It is a
13 | module designed to be easily integrated into applications that need to parse
14 | C source code.
15 | 
16 | What is it good for?
17 | --------------------
18 | 
19 | Anything that needs C code to be parsed. The following are some uses for
20 | **pycparser**, taken from real user reports:
21 | 
22 | * C code obfuscator
23 | * Front-end for various specialized C compilers
24 | * Static code checker
25 | * Automatic unit-test discovery
26 | * Adding specialized extensions to the C language
27 | 
28 | **pycparser** is unique in the sense that it's written in pure Python - a very
29 | high level language that's easy to experiment with and tweak. To people familiar
30 | with Lex and Yacc, **pycparser**'s code will be simple to understand.
31 | 


--------------------------------------------------------------------------------
/test/markups/README.toc.rst.html:
--------------------------------------------------------------------------------
 1 | 
12 | 
13 | 
1   Introduction

14 | 
15 | 
1.1   What is pycparser?

16 | 
pycparser is a parser for the C language, written in pure Python. It is a
17 | module designed to be easily integrated into applications that need to parse
18 | C source code.

19 | 
20 | 
1.2   What is it good for?

21 | 
Anything that needs C code to be parsed. The following are some uses for
22 | pycparser, taken from real user reports:

23 | 
    
24 | 
  • C code obfuscator
    • 
25 | 
  • Front-end for various specialized C compilers
    • 
26 | 
  • Static code checker
    • 
27 | 
  • Automatic unit-test discovery
    • 
28 | 
  • Adding specialized extensions to the C language
    • 
29 | 

30 | 
pycparser is unique in the sense that it's written in pure Python - a very
31 | high level language that's easy to experiment with and tweak. To people familiar
32 | with Lex and Yacc, pycparser's code will be simple to understand.



--------------------------------------------------------------------------------
/test/markups/README.txt:
--------------------------------------------------------------------------------
1 | * One
2 | * Two
3 | 


--------------------------------------------------------------------------------
/test/markups/README.txt.html:
--------------------------------------------------------------------------------
1 | * One
2 | * Two


--------------------------------------------------------------------------------