├── .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.8"
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.8)
62 | mini_portile2 (~> 2.8.2)
63 | racc (~> 1.4)
64 | nokogiri (1.18.8-aarch64-linux-gnu)
65 | racc (~> 1.4)
66 | nokogiri (1.18.8-arm-linux-gnu)
67 | racc (~> 1.4)
68 | nokogiri (1.18.8-arm64-darwin)
69 | racc (~> 1.4)
70 | nokogiri (1.18.8-x86_64-darwin)
71 | racc (~> 1.4)
72 | nokogiri (1.18.8-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.8)
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 <jannis@leidel.info>
6 |
7 | Brandon Keepers <bkeepers@github.com>
8 | Bryan Veloso <bryan@revyver.com>
9 | Chris Wanstrath <chris@ozmm.org>
10 | Dave Abrahams <dave@boostpro.com>
11 | Garen Torikian <garen@github.com>
12 | Gasper Zejn <zejn@kiberpipa.org>
13 | Michael Jones <m.pricejones@gmail.com>
14 | Sam Whited <sam@samwhited.com>
15 | Tyler Chung <zonyitoo@gmail.com>
16 | Vicent Marti <tanoku@gmail.com>
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 <http://creativecommons.org/publicdomain/zero/1.0/>.
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 <div class="document"> 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 <div> off
196 | self.html_body.pop() # pop the ending </div> 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('<a name="%s"></a>\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 <code>, not <tt>
224 | # this also avoids the generation of superfluous <span> 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('</code>')
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('</table>\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('', '<kbd>%s</kbd>' % 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, <<message
75 | #{File.basename expected_file}'s contents are not html equal to output:
76 | #{diff}
77 | message
78 | end
79 | end
80 |
81 | def test_knows_what_it_can_and_cannot_render
82 | assert_equal false, GitHub::Markup.can_render?('README.html', '<h1>Title</h1>')
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', '<h1>Title</h1>').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 = /<p><code>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 "<p>hello <!-- raw HTML omitted --> world</p>\n", GitHub::Markup.render("test.md", "hello <bad> world")
127 | assert_equal "<p>hello <bad> world</p>\n", GitHub::Markup.render("test.md", "hello <bad> world", options: {commonmarker_opts: [:UNSAFE]})
128 |
129 | assert_equal "<p>hello <!-- raw HTML omitted --> world</p>\n", GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "hello <bad> world")
130 | assert_equal "<p>hello <bad> world</p>\n", GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "hello <bad> world", options: {commonmarker_opts: [:UNSAFE]})
131 |
132 | assert_equal "<style>.red{color: red;}</style>\n", GitHub::Markup.render("test.md", "<style>.red{color: red;}</style>", options: {commonmarker_opts: [:UNSAFE]})
133 | assert_equal "<style>.red{color: red;}</style>\n", GitHub::Markup.render("test.md", "<style>.red{color: red;}</style>", 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, "<style>.red{color: red;}</style>", options: {commonmarker_opts: [:UNSAFE]})
136 | assert_equal "<style>.red{color: red;}</style>\n", GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, "<style>.red{color: red;}</style>", 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 <<another-section>> or <<another-section-1>>.
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 | <h1>Document Title</h1>
2 | <div>
3 | <h2>First Section</h2>
4 | <div>
5 | <div>
6 | <ul>
7 | <li>
8 | <p>One</p>
9 | </li>
10 | <li>
11 | <p>Two</p>
12 | </li>
13 | </ul>
14 | </div>
15 | <div>
16 | <p>Refer to <a href="#another-section">Another Section</a> or <a href="#another-section-1">Another Section</a>.</p>
17 | </div>
18 | <div>
19 | <p>Navigate from README.asciidoc to <a href="another-document.asciidoc">another document</a>.</p>
20 | </div>
21 | </div>
22 | </div>
23 | <div>
24 | <h2>Another Section</h2>
25 | <div>
26 | <div>
27 | <table>
28 | <tr>
29 | <td>
30 | <div>Note</div>
31 | </td>
32 | <td>
33 | Here is some source code.
34 | </td>
35 | </tr>
36 | </table>
37 | </div>
38 | <div>
39 | <div>
40 | <pre lang="ruby"><code>puts "Hello, World!"</code></pre>
41 | </div>
42 | </div>
43 | <div>
44 | <ul>
45 | <li>
46 | <p>❏ todo</p>
47 | </li>
48 | <li>
49 | <p>✓ done</p>
50 | </li>
51 | </ul>
52 | </div>
53 | </div>
54 | </div>
55 | <div>
56 | <h2>Another Section</h2>
57 | <div>
58 | <div>
59 | <p>content</p>
60 | </div>
61 | </div>
62 | </div>
--------------------------------------------------------------------------------
/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>H1</h1><h2>H2</h2><p>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.</p><p>You can force a linebreak in your paragraph text<br>thusly.</p><ul>
2 | <li>a list element<ul><li>sub list element</li></ul>
3 | </li>
4 | <li>2nd list element</li>
5 | </ul><pre>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</pre>
--------------------------------------------------------------------------------
/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 | <h1>restructuredText (rst) directives and comments</h1>
2 | <a name="introduction"></a>
3 | <h2>Introduction</h2>
4 | <p>An rst directive starts with two periods, and has a keyword
5 | followed by two colons, like this:</p>
6 | <pre>
7 | .. MyDirective::
8 | </pre>
9 | <p>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.</p>
13 | <p>Display of rst files at github needs to cover two distinct
14 | use-cases:</p>
15 | <ul>
16 | <li>The github display is the primary method for displaying
17 | the file (e.g. for README.rst files)</li>
18 | <li>The github display is incidental to the primary method
19 | for displaying the file (e.g. for readthedocs documentation)</li>
20 | </ul>
21 | <p>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.</p>
24 | <p>It would seem that one possibility for distinguishing these
25 | two cases is to add a github directive to control the display.</p>
26 | <p>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).</p>
29 | <p>Instead, we can assign semantic content to specific comments.</p>
30 | <p>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.</p>
33 | <p>The proposed special comment is:</p>
34 | <pre>
35 | .. github display [on | off]
36 | </pre>
37 | <p>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.</p>
40 | <p>In addition to controlling the display of literal code blocks,
41 | this also allows you to show comments specifically for github.</p>
42 | <p>For example, somebody could place this at the top of their file:</p>
43 | <pre>
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 | </pre>
50 | <a name="tests"></a>
51 | <h2>Tests</h2>
52 | <p>By default, unknown directives should be displayed.</p>
53 | <pre>
54 | .. UnknownDirective:: This is an unknown directive
55 |
56 | it has a lot of stuff underneath it
57 |
58 | </pre>
59 | <p>But we can turn this off, and the next directive should
60 | not be displayed.</p>
61 | <p>Or we can turn it back on...</p>
62 | <pre>
63 | .. UnknownDirective:: This is an unknown directive (3)
64 |
65 | it has a lot of stuff underneath it
66 |
67 | </pre>
68 | <p>Here is a comment that should display at github</p>
69 | <pre>
70 |
71 | YOU SHOULD SEE THIS!
72 | </pre>
73 | <p>And here is a comment that should not display at github</p>
74 | <p>This concludes the tests.</p>
--------------------------------------------------------------------------------
/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 | <div>
2 | <p>This test verifies the author can disable the document title by adding <code>:!showtitle:</code> to the document header.</p>
3 | </div>
--------------------------------------------------------------------------------
/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 | <h2>Literate CoffeeScript Test</h2>
2 | <blockquote>
3 | <p>Taken from <a href="https://github.com/jashkenas/coffee-script/blob/master/test/literate.litcoffee">https://github.com/jashkenas/coffee-script/blob/master/test/literate.litcoffee</a></p>
4 | </blockquote>
5 | <p>comment comment</p>
6 | <pre><code>test "basic literate CoffeeScript parsing", ->
7 | ok yes
8 | </code></pre>
9 | <p>now with a...</p>
10 | <pre><code>test "broken up indentation", ->
11 | </code></pre>
12 | <p>... broken up ...</p>
13 | <pre><code> do ->
14 | </code></pre>
15 | <p>... nested block.</p>
16 | <pre><code> ok yes
17 | </code></pre>
18 | <p>Code must be separated from text by a blank line.</p>
19 | <pre><code>test "code blocks must be preceded by a blank line", ->
20 | </code></pre>
21 | <p>The next line is part of the text and will not be executed.
22 | fail()</p>
23 | <pre><code> ok yes
24 | </code></pre>
25 | <p>Code in <code>backticks is not parsed</code> and...</p>
26 | <pre><code>test "comments in indented blocks work", ->
27 | do ->
28 | do ->
29 | # Regular comment.
30 |
31 | ###
32 | Block comment.
33 | ###
34 |
35 | ok yes
36 | </code></pre>
37 | <p>Regular <a href="http://example.com/markdown">Markdown</a> features,
38 | like links and unordered lists, are fine:</p>
39 | <ul>
40 | <li>
41 | <p>I</p>
42 | </li>
43 | <li>
44 | <p>Am</p>
45 | </li>
46 | <li>
47 | <p>A</p>
48 | </li>
49 | <li>
50 | <p>List</p>
51 | </li>
52 | </ul>
53 | <p>Tabs work too:</p>
54 | <p>test "tabbed code", ->
55 | ok yes</p>
--------------------------------------------------------------------------------
/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 | <!-- Old format -->
538 | <msg timestamp="20231108 15:36:34.278" level="INFO">Hello world!</msg>
539 | <status status="PASS" starttime="20231108 15:37:35.046" endtime="20231108 15:37:35.046"/>
540 |
541 | <!-- New format -->
542 | <msg time="2023-11-08T15:36:34.278343" level="INFO">Hello world!</msg>
543 | <status status="PASS" start="2023-11-08T15:37:35.046153" elapsed="0.000161"/>
544 |
545 | The new format is standard compliant, contains more detailed times, makes the elapsed
546 | time directly available and makes the `<status>` 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 | <!-- Old format -->
570 | <kw name="Log" library="BuiltIn">...</kw>
571 | <kw name="Number of horses should be" sourcename="Number of ${animals} should be" library="my_resource">...</kw>
572 |
573 | <!-- New format -->
574 | <kw name="Log" owner="BuiltIn">...</kw>
575 | <kw name="Number of horses should be" source_name="Number of ${animals} should be" owner="my_resource">...</kw>
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 `<status>` element, and they have been present already earlier with
582 | tests and suites. Related to this, control structured cannot anymore have `<doc>`.
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 `<type>` elements.
681 | The name is available as the `name` attribute of `<type>` 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 <https://github.com/yanne>`_ (part time).
831 | In addition to work done by them, the community has provided some great contributions:
832 |
833 | - `Ygor Pontelo <https://github.com/ygorpontelo>`__ 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 <https://github.com/totu>`__ 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 <https://github.com/psaikkonen>`__ added dark mode to reports
842 | and logs (`#3725`_).
843 |
844 | - `René <https://github.com/Snooz82>`__ 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 <https://github.com/robinmackaij>`__ added type hints to modules that
849 | did not yet have them under the public `robot.api` package (`#4841`_).
850 |
851 | - `Mark Moberts <https://github.com/MobyNL>`__ added case-insensitive list and
852 | dictionary comparison support to the Collections library (`#4343`_).
853 |
854 | - `Daniel Biehl <https://github.com/d-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 <https://robocon.io>`__ 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=<value>` 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 <https://github.com/robotframework/robotframework/issues?q=milestone%3Av7.0>`__.
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 | <ul>
2 | <li>One</li>
3 | <li>Two</li>
4 | </ul>
--------------------------------------------------------------------------------
/test/markups/README.mediawiki:
--------------------------------------------------------------------------------
1 | [[Home|» JRuby Project Wiki Home Page]]
2 | <h1>Embedding JRuby</h1>
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 | <tt>one-<two</tt>
10 | <pre>a-b</pre>
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 <code>org.jruby.RubyInstanceConfig</code>. With the other APIs, configuration options can only be set globally, via the <code>System</code> properties.
20 | # Embed Core offers several shortcuts, such as loading scripts from a <code>java.io.InputStream</code>, 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]]<ref>This link goes nowhere.</ref> page.
28 |
29 | = References =
30 | <references/>
31 |
--------------------------------------------------------------------------------
/test/markups/README.mediawiki.html:
--------------------------------------------------------------------------------
1 | <p><a href="Home">» JRuby Project Wiki Home Page</a>
2 | </p><h1>Embedding JRuby</h1>
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 | <p></p><table summary="Contents"><tr><td>
6 | <div><h2>Table of Contents</h2></div>
7 | <ul>
8 | <li>
9 | <a href="#Red_Bridge_JRuby_Embed">Red Bridge (JRuby Embed)</a><ul><li><a href="#Features_of_Red_Bridge">Features of Red Bridge</a></li></ul>
10 | </li>
11 | <li><a href="#Previous_Embedding_JRuby_Page">Previous Embedding JRuby Page</a></li>
12 | <li><a href="#References">References</a></li>
13 | </ul>
14 | </td></tr></table>
15 |
16 |
17 | <h1>
18 | <a name="Red_Bridge_JRuby_Embed"></a>Red Bridge (JRuby Embed)
19 | </h1>
20 |
21 |
22 |
23 | <p><tt>one-<two</tt>
24 | </p><pre>a-b</pre>
25 |
26 | <p>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 <a href="DirectJRubyEmbedding">legacy API</a> should still work, but we strongly recommend Red Bridge for all new projects.
27 | </p>
28 |
29 | <h2>
30 | <a name="Features_of_Red_Bridge"></a>Features of Red Bridge
31 | </h2>
32 |
33 |
34 | <p>Red Bridge consists of two layers: Embed Core on the bottom, and implementations of <a href="http://www.jcp.org/en/jsr/detail?id=223" target="_blank">JSR223</a> and <a href="http://jakarta.apache.org/bsf/" target="_blank">BSF</a> 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 | </p>
36 | <p>Which API should you use? For projects where Ruby is the only scripting language involved, we recommend Embed Core for the following reasons:
37 | </p>
38 |
39 |
40 |
41 | <p></p><ol>
42 | <li>With Embed Core, you can create several Ruby environments in one JVM, and configure them individually (via <code>org.jruby.RubyInstanceConfig</code>. With the other APIs, configuration options can only be set globally, via the <code>System</code> properties.</li>
43 | <li>Embed Core offers several shortcuts, such as loading scripts from a <code>java.io.InputStream</code>, or returning Java-friendly objects from Ruby code. These allow you to skip a lot of boilerplate.</li>
44 | </ol>
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 | <p>The full <a href="http://jruby-embed.kenai.com/docs/" target="_blank">API documentation</a> has all the gory details. It's worth talking about a couple of the finer points here.
48 | </p>
49 |
50 | <h1>
51 | <a name="Previous_Embedding_JRuby_Page"></a>Previous Embedding JRuby Page
52 | </h1>
53 |
54 |
55 | <p>We recommend using Embed Core; however, if you're maintaining code that uses the old API, you can find its documentation on the <a href="JavaIntegration">legacy embedding</a><sup>[<a href="#cite_note-1">1</a>]</sup> page.
56 | </p>
57 |
58 | <h1>
59 | <a name="References"></a>References
60 | </h1>
61 |
62 |
63 | <p></p><ol><li>
64 | <b><a href="#cite_ref-1-0">^</a> </b> This link goes nowhere.</li></ol>
--------------------------------------------------------------------------------
/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 <pre> 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 <th> 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 | <h1>org-ruby</h1>
2 | <table>
3 | <tr>
4 | <td>Status:</td>
5 | <td>Under Development</td>
6 | </tr>
7 | <tr>
8 | <td>Location:</td>
9 | <td><a href="http://github.com/wallyqs/org-ruby">http://github.com/wallyqs/org-ruby</a></td>
10 | </tr>
11 | <tr>
12 | <td>Version:</td>
13 | <td>0.9.0</td>
14 | </tr>
15 | </table>
16 | <h1>1 Description</h1>
17 | <p>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.”</p>
22 | <h1>2 History</h1>
23 | <h2>2.1 2014-02-08: Version 0.9.0</h2>
24 | <ul>
25 | <li>Let’s make sure <code>#+INCLUDE:</code> is not supported</li>
26 | </ul>
27 | <ul>
28 | <li>And confirm that syntax highlight is supported</li>
29 | </ul>
30 | <pre lang="ruby">
31 | module GitHub
32 | module Markup
33 | VERSION = 'test'
34 | Version = VERSION
35 | end
36 | end
37 | </pre>
38 | <h2>2.2 2009-12-30: Version 0.5.1</h2>
39 | <ul>
40 | <li>Minor enhancement: Recognize lines starting with “:” as examples.</li>
41 | <li>Minor enhancement: Recognize #+BEGIN_SRC as source blocks</li>
42 | <li>Minor enhancement: Add “src” and “example” classes to <pre> blocks.</li>
43 | </ul>
44 | <h2>2.3 2009-12-30: Version 0.5.0</h2>
45 | <ul>
46 | <li>Parse (but not necessarily <b>use</b>) in-buffer settings. The following
47 | in-buffer settings <b>are</b> used:
48 | <ul>
49 | <li>Understand the #+TITLE: directive.</li>
50 | <li>Exporting todo keywords (option todo:t)</li>
51 | <li>Numbering headlines (option num:t)</li>
52 | <li>Skipping text before the first headline (option skip:t)</li>
53 | <li>Skipping tables (option |:nil)</li>
54 | <li>Custom todo keywords</li>
55 | <li>EXPORT_SELECT_TAGS and EXPORT_EXCLUDE_TAGS for controlling parts of
56 | the tree to export</li>
57 | </ul>
58 | </li>
59 | <li>Rewrite “file:(blah).org” links to “http:(blah).html” links. This
60 | makes the inter-links to other org-mode files work.</li>
61 | <li>Uses <th> tags inside table rows that precede table separators.</li>
62 | <li>Bugfixes:
63 | <ul>
64 | <li>Headings now have HTML escaped.</li>
65 | </ul>
66 | </li>
67 | </ul>
68 | <h2>2.4 2009-12-29: Version 0.4.2</h2>
69 | <ul>
70 | <li>Got rid of the extraneous newline at the start of code blocks.</li>
71 | <li>Everything now shows up in code blocks, even org-mode metadata.</li>
72 | <li>Fixed bugs:
73 | <ul>
74 | <li>Regressed smart double quotes with HTML escaping. Added a test
75 | case and fixed the regression.</li>
76 | </ul>
77 | </li>
78 | </ul>
79 | <h2>2.5 2009-12-29: Version 0.4.1</h2>
80 | <ul>
81 | <li>HTML is now escaped by default</li>
82 | <li>org-mode comments will show up in a code block.</li>
83 | </ul>
84 | <h2>2.6 2009-12-29: Version 0.4</h2>
85 | <ul>
86 | <li>The first thing output in HTML gets the class “title”</li>
87 | <li>HTML output is now indented</li>
88 | <li>Proper support for multi-paragraph list items.
89 | <p>See? This paragraph is part of the last bullet.</p>
90 | </li>
91 | <li>Fixed bugs:
92 | <ul>
93 | <li>“rake spec” wouldn’t work on Linux. Needed “require ‘rubygems’”.</li>
94 | </ul>
95 | </li>
96 | </ul>
97 | <h2>2.7 2009-12-27: Version 0.3</h2>
98 | <ul>
99 | <li>Uses rubypants to get better typography (smart quotes, ellipses, etc…).</li>
100 | <li>Fixed bugs:
101 | <ul>
102 | <li>Tables and lists did not get properly closed at the end of file</li>
103 | <li>You couldn’t do inline formatting inside table cells</li>
104 | <li>Characters in PRE blocks were not HTML escaped.</li>
105 | </ul>
106 | </li>
107 | </ul>
108 | <h2>2.8 2009-12-26: Version 0.2</h2>
109 | <ul>
110 | <li>Added <code>to_html</code> output on the parser.</li>
111 | <li>Added support for the full range of inline markup: <b>bold</b>,
112 | <i>italic</i>, <code>code</code>, <code>verbatim</code>, underline, <del>strikethrough</del>.</li>
113 | <li>Lots of refactoring to make the code more maintainable.</li>
114 | </ul>
115 | <h2>2.9 2009-12-23: Version 0.1</h2>
116 | <ul>
117 | <li>Added support for block code, like this:
118 | <pre>
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 | </pre>
134 | </li>
135 | <li>Major code cleanup: Created the <code>OutputBuffer</code> class that
136 | greatly simplified a lot of the messiness of <code>textile</code>
137 | conversion.</li>
138 | <li>Added support for line breaks within list items.</li>
139 | </ul>
--------------------------------------------------------------------------------
/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<src/parser/> directory. The
27 | parser proper is composed of three source files, F<grammar.pg> which is a
28 | Perl6Grammar file, and F<actions.pm> which is the associated actions file
29 | written in NQP, and F<grammar-oper.pm> which is the operator precedence parser.
30 | In addition, several helper functions used by the parser are located in
31 | C<src/internals>.
32 |
33 | =item * The second component is the library of builtin functions in the
34 | C<src/builtins/> 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<toolbox/>.
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 | <h1>Matrixy</h1>
2 |
3 | <h2>INTRODUCTION</h2>
4 |
5 | <p>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.</p>
6 |
7 | <h2>ABOUT</h2>
8 |
9 | <p>Primary goals are:</p>
10 |
11 | <ul>
12 |
13 | <li>
14 | <p>Create a working compiler that understands the majority of the MATLAB/Octave programming language.</p>
15 |
16 | </li>
17 | </ul>
18 |
19 | <h2>IMPLEMENTATION</h2>
20 |
21 | <p>This project is broken into three primary components:</p>
22 |
23 | <ul>
24 |
25 | <li>
26 | <p>The first is the parser, located in the <code>src/parser/</code> directory. The parser proper is composed of three source files, <i>grammar.pg</i> which is a Perl6Grammar file, and <i>actions.pm</i> which is the associated actions file written in NQP, and <i>grammar-oper.pm</i> which is the operator precedence parser. In addition, several helper functions used by the parser are located in <code>src/internals</code>.</p>
27 |
28 | </li>
29 | <li>
30 | <p>The second component is the library of builtin functions in the <code>src/builtins/</code> 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.</p>
31 |
32 | </li>
33 | <li>
34 | <p>A number of library functions are written in M, or mostly M with some inline PIR code in <code>toolbox/</code>.</p>
35 |
36 | </li>
37 | </ul>
38 |
39 | <h2>DEPENDENCIES</h2>
40 |
41 | <p>Matrixy depends on these dependencies:</p>
42 |
43 | <h3>Parrot</h3>
44 |
45 | <p>To get a proper version of Parrot to build Matrixy, you will need to check out and build Parrot from source:</p>
46 |
47 | <pre><code>svn co http://svn.parrot.org/parrot/trunk parrot
48 | cd parrot
49 | perl Configure.pl
50 | make && make test && make install-dev</code></pre>
51 |
52 | <h3>Parrot-Linear-Algebra</h3>
53 |
54 | <p>The linear algebra package for Parrot is available separately and provides functionality required by Matrixy. This includes matrix data types and matrix manipulation libraries</p>
55 |
56 | <h2>BUILDING</h2>
57 |
58 | <p>Once all dependencies are in place, you can build Matrixy using this sequence of commands:</p>
59 |
60 | <pre><code>perl Configure.pl
61 | nmake test</code></pre>
62 |
63 | <h2>TODO</h2>
64 |
65 | <pre><code>* Parser
66 | * Standard Builtins
67 | * Test against Octave Test Suite.</code></pre>
68 |
69 | <h2>BUGS</h2>
70 |
71 | <p>Lots!</p>
72 |
73 | <h2>CONTACT</h2>
74 |
75 | <p>If you need to contact the Matrixy team, go to the project home page at:</p>
76 |
77 | <p>www.github.com\Whiteknight\matrixy</p>
--------------------------------------------------------------------------------
/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 | <ul>
2 | <li>
3 | <p>One</p>
4 | </li>
5 | <li>
6 | <p>Two</p>
7 | </li>
8 | </ul>
9 |
10 | <p>This is an <a href="http://github.com">absolute link</a>. So is this: <a href="http://github.com">github.com</a></p>
11 |
12 | <p>This is a <a href="rawr.html">relative link</a>. So is this: <a href="rawr.html">rawr.html</a></p>
--------------------------------------------------------------------------------
/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 <label_for_header_2_>`_
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 | <p><strong>RAW HTML!</strong></p><style> p {color:blue;} </style>
93 |
--------------------------------------------------------------------------------
/test/markups/README.rst.html:
--------------------------------------------------------------------------------
1 | <h1>Header 1</h1>
2 | <h2>Subtitle</h2>
3 | <p>Example text.</p>
4 | <div>
5 | <p><a href="#top">Table of Contents</a></p>
6 | <ul>
7 | <li><a href="#header-2">Header 2</a></li>
8 | <li><a href="#field-list">Field list</a></li>
9 | </ul>
10 | </div>
11 | <a name="header-2"></a>
12 | <a name="label-for-header-2"></a>
13 | <h2><a href="#toc-entry-1">Header 2</a></h2>
14 | <ol>
15 | <li>Blah blah <code>code</code> blah</li>
16 | <li>More <code>code</code>, hooray</li>
17 | <li>Somé UTF-8°</li>
18 | <li><a href="#label-for-header-2">Link to the above header</a></li>
19 | </ol>
20 | <p>The UTF-8 quote character in this table used to cause python to go boom. Now docutils just silently ignores it.</p>
21 | <table>
22 | Things that are Awesome (on a scale of 1-11)
23 |
24 |
25 |
26 |
27 | <tbody valign="top">
28 | <tr>
29 | <td>Thing</td>
30 | <td>Awesomeness</td>
31 | </tr>
32 | <tr>
33 | <td>Icecream</td>
34 | <td>7</td>
35 | </tr>
36 | <tr>
37 | <td>Honey Badgers</td>
38 | <td>10.5</td>
39 | </tr>
40 | <tr>
41 | <td>Nickelback</td>
42 | <td>-2</td>
43 | </tr>
44 | <tr>
45 | <td>Iron Man</td>
46 | <td>10</td>
47 | </tr>
48 | <tr>
49 | <td>Iron Man 2</td>
50 | <td>3</td>
51 | </tr>
52 | <tr>
53 | <td>Tabular Data</td>
54 | <td>5</td>
55 | </tr>
56 | <tr>
57 | <td>Made up ratings</td>
58 | <td>11</td>
59 | </tr>
60 | </tbody>
61 | </table>
62 | <pre>
63 | A block of code
64 | </pre>
65 | <pre lang="python">
66 | python.code('hooray')
67 | </pre>
68 | <pre lang="python">
69 | python.code('hello world')
70 | </pre>
71 | <pre lang="python">
72 | >>> some_function()
73 | 'result'
74 | </pre>
75 | <pre lang="pycon">
76 | >>> some_function()
77 | 'result'
78 | </pre>
79 | <table>
80 |
81 |
82 |
83 |
84 | <tbody valign="top">
85 | <tr>
86 | <td>Travis</td>
87 | <td><a href="http://travis-ci.org/tony/pullv">http://travis-ci.org/tony/pullv</a></td>
88 | </tr>
89 | <tr>
90 | <td>Docs</td>
91 | <td><a href="http://pullv.rtfd.org">http://pullv.rtfd.org</a></td>
92 | </tr>
93 | <tr>
94 | <td>API</td>
95 | <td><a href="http://pullv.readthedocs.org/en/latest/api.html">http://pullv.readthedocs.org/en/latest/api.html</a></td>
96 | </tr>
97 | <tr>
98 | <td>Issues</td>
99 | <td><a href="https://github.com/tony/pullv/issues">https://github.com/tony/pullv/issues</a></td>
100 | </tr>
101 | <tr>
102 | <td>Source</td>
103 | <td><a href="https://github.com/tony/pullv">https://github.com/tony/pullv</a></td>
104 | </tr>
105 | </tbody>
106 | </table>
107 | <a href="https://scan.coverity.com/projects/621">
108 | <img alt="Coverity Scan Build Status" src="https://scan.coverity.com/projects/621/badge.svg">
109 | </a>
110 | <img alt="Coverity Scan Build Status" src="https://scan.coverity.com/projects/621/badge.svg">
111 | <a name="field-list"></a>
112 | <h2><a href="#toc-entry-2">Field list</a></h2>
113 | <table frame="void" rules="none">
114 |
115 |
116 | <tbody valign="top">
117 | <tr><th colspan="2">123456789 123456789 123456789 123456789 123456789 1:</th></tr>
118 | <tr>
119 | <td> </td>
120 | <td>Uh-oh! This name is too long!</td>
121 | </tr>
122 | <tr>
123 | <th>123456789 123456789 123456789 123456789 1234567890:</th>
124 | <td>this is a long name,
125 | but no problem!</td>
126 | </tr>
127 | <tr>
128 | <th>123456789 12345:</th>
129 | <td>this is not so long, but long enough for the default!</td>
130 | </tr>
131 | <tr>
132 | <th>123456789 1234:</th>
133 | <td>this should work even with the default :)</td>
134 | </tr>
135 | </tbody>
136 | </table>
137 | <p><a href="mailto:someone@somewhere.org">someone@somewhere.org</a></p>
138 | <p>Press <kbd>Ctrl+C</kbd> to quit</p>
139 | <p><strong>RAW HTML!</strong></p> 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 | <h1>Header 1</h1>
2 | <p>Example text.</p>
3 | <a name="header-2"></a>
4 | <h2>Header 2</h2>
5 | <ol>
6 | <li>Blah blah <code>code</code> blah</li>
7 | <li>More <code>code</code>, hooray</li>
8 | <li>Somé UTF-8°</li>
9 | </ol>
10 | <table>
11 |
12 |
13 |
14 |
15 | <tbody valign="top">
16 | <tr>
17 | <td>Travis</td>
18 | <td><a href="http://travis-ci.org/tony/pullv">http://travis-ci.org/tony/pullv</a></td>
19 | </tr>
20 | <tr>
21 | <td>Docs</td>
22 | <td><a href="http://pullv.rtfd.org">http://pullv.rtfd.org</a></td>
23 | </tr>
24 | <tr>
25 | <td>API</td>
26 | <td><a href="http://pullv.readthedocs.org/en/latest/api.html">http://pullv.readthedocs.org/en/latest/api.html</a></td>
27 | </tr>
28 | <tr>
29 | <td>Issues</td>
30 | <td><a href="https://github.com/tony/pullv/issues">https://github.com/tony/pullv/issues</a></td>
31 | </tr>
32 | <tr>
33 | <td>Source</td>
34 | <td><a href="https://github.com/tony/pullv">https://github.com/tony/pullv</a></td>
35 | </tr>
36 | </tbody>
37 | </table>
--------------------------------------------------------------------------------
/test/markups/README.textile:
--------------------------------------------------------------------------------
1 | * One
2 | * Two
3 |
--------------------------------------------------------------------------------
/test/markups/README.textile.html:
--------------------------------------------------------------------------------
1 | <ul>
2 | <li>One</li>
3 | <li>Two</li>
4 | </ul>
--------------------------------------------------------------------------------
/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 | <h1>Document Title</h1>
2 | <div>
3 | <div>Contents</div>
4 | <ul>
5 | <li>
6 | <a href="#section-a">Section A</a>
7 | <ul>
8 | <li><a href="#subsection-a-1">Subsection A-1</a></li>
9 | <li><a href="#subsection-a-2">Subsection A-2</a></li>
10 | </ul>
11 | </li>
12 | <li>
13 | <a href="#section-b">Section B</a>
14 | <ul>
15 | <li><a href="#subsection-b-1">Subsection B-1</a></li>
16 | <li><a href="#subsection-b-2">Subsection B-2</a></li>
17 | </ul>
18 | </li>
19 | </ul>
20 | </div>
21 | <div>
22 | <h2>Section A</h2>
23 | <div>
24 | <div>
25 | <h3>Subsection A-1</h3>
26 |
27 | </div>
28 | <div>
29 | <h3>Subsection A-2</h3>
30 |
31 | </div>
32 | </div>
33 | </div>
34 | <div>
35 | <h2>Section B</h2>
36 | <div>
37 | <div>
38 | <h3>Subsection B-1</h3>
39 |
40 | </div>
41 | <div>
42 | <h3>Subsection B-2</h3>
43 |
44 | </div>
45 | </div>
46 | </div>
--------------------------------------------------------------------------------
/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 | <div>
2 | <p><a href="#top">Contents</a></p>
3 | <ul>
4 | <li>
5 | <a href="#introduction">1 Introduction</a><ul>
6 | <li><a href="#what-is-pycparser">1.1 What is pycparser?</a></li>
7 | <li><a href="#what-is-it-good-for">1.2 What is it good for?</a></li>
8 | </ul>
9 | </li>
10 | </ul>
11 | </div>
12 | <a name="introduction"></a>
13 | <h2>1 Introduction</h2>
14 | <a name="what-is-pycparser"></a>
15 | <h3>1.1 What is pycparser?</h3>
16 | <p><strong>pycparser</strong> 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.</p>
19 | <a name="what-is-it-good-for"></a>
20 | <h3>1.2 What is it good for?</h3>
21 | <p>Anything that needs C code to be parsed. The following are some uses for
22 | <strong>pycparser</strong>, taken from real user reports:</p>
23 | <ul>
24 | <li>C code obfuscator</li>
25 | <li>Front-end for various specialized C compilers</li>
26 | <li>Static code checker</li>
27 | <li>Automatic unit-test discovery</li>
28 | <li>Adding specialized extensions to the C language</li>
29 | </ul>
30 | <p><strong>pycparser</strong> 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, <strong>pycparser</strong>'s code will be simple to understand.</p>
--------------------------------------------------------------------------------
/test/markups/README.txt:
--------------------------------------------------------------------------------
1 | * One
2 | * Two
3 |
--------------------------------------------------------------------------------
/test/markups/README.txt.html:
--------------------------------------------------------------------------------
1 | * One
2 | * Two
--------------------------------------------------------------------------------