diff --git a/.flake8 b/.flake8 index 48cadb85823..e01c0e5c803 100644 --- a/.flake8 +++ b/.flake8 @@ -17,6 +17,7 @@ ignore = SIM223, SIM401, SIM907, + SIM910, exclude = .git, .tox, @@ -26,8 +27,5 @@ exclude = doc/_build/*, sphinx/search/*, doc/usage/extensions/example*.py, -application-import-names = sphinx -import-order-style = smarkets per-file-ignores = tests/*: E501 - sphinx/util/jsdump.py: SIM905 diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs new file mode 100644 index 00000000000..1fe7619b4ea --- /dev/null +++ b/.git-blame-ignore-revs @@ -0,0 +1,295 @@ +# .git-blame-ignore-revs +# Commits listed in this file are ignored by default in GitHub's interactive +# 'blame' view (e.g. https://github.com/sphinx-doc/sphinx/blame/master/README.rst). +# Lines beginning with a '#' character are ignored, and may be used as comments. + +# Commits should be listed as one unabbreviated SHA-1 per line, with an +# explanatory comment above the entry. Maintain graph ordering, with later +# commits listed after earlier commits in this file. + +# For more details, see https://git-scm.com/docs/git-blame +# git blame --ignore-revs-file .git-blame-ignore-revs +# git config blame.ignoreRevsFile .git-blame-ignore-revs + + +# 2008 copyright year update +db0bbcb136c90beffabf04da959ff5a8386ba7e5 + + +# Switch copyright and licence fields style +0b28b3e6f6666383c2eb497972328af8e6fc5fef + + +# 2009 copyright year update +5df8e162f9b2740ac2b74fa15bc3c0be8b56a02b + + +# 2010 copyright year update +f6a56192d150091e10bc8726d68e0632f395ee54 +38e120848fe3c0462e880c0c635f964fad2c3720 + + +# Add copyright headers to theme files +f81f8d93d13d07d1e409f8a21e5602f0ad7d034c + + +# 2011 copyright year update +0e1db6ad90a272ff7e5cf86039df905ae91ac4df + + +# 2013 copyright year update +151856819c212229f6f58a8a2cbf9223a4191f94 +52515eeb8622fb484132df55a95dcb4acdacd6a2 + + +# 2014 copyright year update +e0300313215fb55d24aa5bda1b68eedd798310b6 +b5430045ae56dc8a9d53a94a3473cd682720bfde + + +# 2015 copyright year update +567d52f199d74a9ec84c491b5d7c9a4555912db0 +d79bedb69a790640fafdc43ab47104f0c0be98b7 + + +# 2016 copyright year update +46d7e8558e49f9b314ff77dbbe3ca6d2691c5895 +6b7b51a55aa0dc419d9fd8dae17bbec197bd2724 + + +# 2017 copyright year update +c57e47e0424be5d742ee6d5daf913274c6da069f +bf3f9ef3ecc94067a2f9b17f2c863e723cf3e7af + + +# 2018 copyright year update +2426cedb8b12b7a59270e55f2f26d63d0014a28f +5562e76585611928ad8628cb9a40a0eb2b3d87fe + + +# Insert 'from sphinx.util.typing import unicode' +3c99d0060557bb33a482f3fe74c1b665fb3de010 + + +# Replace all occurrences of 'unicode' with 'str' +6bc357140dbb074eb0d590c1226009f83f97862e + + +# Remove encoding attribute from Python files +bade33c7e490655c3f5b46d374129294f70449aa + + +# 2019 copyright year update +1b1ebd2c7539ebf6a1dfa1ea247e659f98fa9eaf +da3075d0b7474846a3f86c1ddd272d9640982e02 + + +# Use PEP 484 style type annotations (function annotations) +afbf6d811dd4fc514d63e9dc3d6bee78d97b8a0c +850bfa07d278fca79965c0fc5c44116e36062ffc +ba8bf2c2cec2dbbabc5c742677ff02f45c894047 +3be478f0b51d47694ad31aabd1c6204b4d34df68 +316c61b172a8f756ca219c5f9c54ff29ef6cd782 +1fc0985df73ee31f836bcece622e89c36b45254f +20f2845e218ffee6461868a4c92f0ccd98f6b3ba +d9469c08ed02634df11cf9dc7a3df3e512cedb8b +d59e362f5f7d1df333ad6c3b1c24fabd000230cc +47d9035bca9e83d6db30a0726a02dc9265bd66b1 +24f8a3caf03ee2c11a1746413d68a572cb59f23e +f3e45e485e9caefb9099e0598549b73231401264 +39c7ee955b71745d2503f61b5ba488345e1b38a4 +dd4741c352ab45e28c9b0c4fbd2d366d224be503 +086eac39148af091905d0f81bb484c72055c3c0e +2900179436580a53fcf0a9b2b15e31ef8e259979 +b5276b3965388e7b7264a42d1a442b8c734b1877 +5115fb0172c3ae42f326ed7c50e2aa10917dfb94 +9ba216223a3b7d6d0888e4588709d3923557f096 +17e26bf29fa6d8f2f40b9da47b1131c30680cd80 +a3c9edfbe6d50b486ea28876e47b7d6e27379916 +073b92d45a59eb5065d304fbaf0fc2d2ff88c5e8 +1e70267cc8a3a31dbadea4e72971bec4c60cb255 +8aa04eb85537e6607718fad35b70758747258248 +086e46bdf212063e5cde6964ab02a24d6f6fe5fc +09d8526ee772f10cd04eb579a8b40e540a99fdc5 +1659cc264cb0311bb546673c7c5a4749a2915de9 +ffe5e129c3bcb4a0ecd80e5863c92d94910ecffd +d141fbf054cf3885538820363460e9e729e3cef0 +60b1cec446ef184adc91bdaaca93980c49312ba7 +9c5b26756a79ae9bbbe6bf385019687494a85649 +3f5ce569b63163ca4b69aba72ac5cdd445a67dd0 +e14c76d94228bf01102417317b1c1613b7cebc86 +4db7a815289964dc4caab065e326b52ad2ec2144 +acab4029afe8b3ecafa4a5c7e5f6b51482349cd8 +cc3022b7f059333c0892f0c37a28db19a5e26e8d +ec2c8f7194d1089534dab058d059bdc7baac2417 +f9a74b08f9636284f7692fd8f865dbf387c18daf +f442de643bbf3f2df45578dff665b8f80b980ac4 +dbceb69b43fd5b88259a8ab2839167b3db30e086 +436bc15d09c178b70ce404380bd834c6b93bc8dd +a2a5bf98df13f55420794f26f0e468cd9c01dc5b +ccdad403c8f7df3669516c140f3fbbd8dd09dda5 +1ab5e279f8a60865e31194d91bb021eeca02c31c +bedab2983244b423fef7f28dec06673aec2f0262 +18924f991d6cc169830e76451126d982415643b1 +f8ddc44c503b8285ec79cc2450caaa67bf487928 +89e9f199b421752e81be6829ebebd6df49a177cc +dd5f968bfaa80169359ddfaf2f07e9cde9a6f7a5 +9a085794a2e13effeebacfeaa443221bfb5125e0 +5716aa7a74b114f56619547b5ab8155c380a4696 +13bd831110390c4bbd5248a376291379edbd26e9 +7f2e9cebf95cb4d300ffb9bc7de8e40691647406 +4488815dca86afe623049539dc5d1aaf4e2c428e +1d371c2cebe4cc598918691aa19043236dd43eef +7609e67d19ba000b7a01729e543cd0dc6b08d08e +320661ee945bb74ce1433f710f5da6728416bd2b +62e5f6935b85db66113c23491a3cf261d7af4ef4 +6c47f7d4a2ff5cbd26d632e2dfc5e426f6500341 +3a81e0ad7d4f2db4326fbb3f8346a08fa3e09051 +ee6e44a04f40c7f88d6cb9624068c352de8149db +f6d0cb8f3ad5a29e5e5c4f0c85f5736904291703 +f5620910fcad6ff7db708d809a7a8e1f1961fe90 +1b597dc4509b393cf7b0107738beb9ee8c440a1d +b93672c4d45f0574e144966d1b4b92a96beb3abb +fdc2bee7d35c41098e924070ee38b3538ed51ab8 +5cc5c53435bd933cf93d09700324e8b808eee39e +9148b6e653fd416e185fa2a1d5c91df279999831 +0c721434a02958334d0b71396ab73b09a021a6f2 +462902aea649ecb6b953651552a1f44f58844e18 +30ddf70742941bf22f78930fd9e25e6b0271e92c +c0b267b5a61a06e80b344ecf925f4b049d93c7bf +ad81d788f9f6276cf26f46fcc9c9d3b275506e4b +22fd569f9b5d28ce42a157ba8fa2ba1c5af0b09e +728bf8c9d892057197393f62f4ec4a7a029ad20f +d057c5e6d7c1f0836db14c5546990c6f370972bf +e67f5db2969d3fe14ade5b30e9081ff1ce9adf16 +8c946570dc6227c70b690a33320916cb7f9dae9e +d57e338510d10e3685324f3029b15ab41a3817c0 +4ba85181177e732b032486324cc64a0f3bc1ac3d +eb07a0fee19a0a3e205755c7923e40a56a7a28db +0832291883a793fb3e025a18eae505bb7182ffab +3a74ef89b3b386daacd4dfa0752536b3ad9aa402 +dd9d02007c5f2dbeb2a294391b035ff445bae9eb +c270efccd7da379895541b6e302c78990b943b2f +0a98664866053312b1aef539f98c656fb5a7e65f +f0579fcd4a6a5380b896e8baac346a7b98dd70ca +e3eb0cc95d64afa3939ad37b1fc95fa24d06a32a +f82d6c429b6379663b71cba783e780535d73343b +dcff6d7cbceea55f681284c327b24169f4285ae2 +31f93f38dc631b7192ab2dcecc151714835b714d +6a9b6d20dc7aa7ff5710c0d9e10c38953106e489 +389195632473153bb0b0d4b35cb70da059235bd8 +c68664ae70dcdbdb20a782001fefd0f09f2206a5 +7806a92e3dcca1231c654c7417d441db98844510 +39ec5e0debecf2f5d06bfb8548f2045cce101639 +0cad96233b8b6e6e821183cf28f476ed6f53836e +17c719c8de872cc9747040f886e81086641b8cce +f076afd920b0b36d63608a63fae72f484d4bd65e +be673a714db80d3596f811ccf5421d5653cbe559 +66b123a9a71dba0b8f26fe85ec218e7fe32dcfa3 +58847682ccd91762608f3a5a023b244675e8470b +d0fedc3a4b9f50af53e9f930fdd50deee213a12c +e67e0432b55efc4bcf0bc8794b6a7689714ab72b +986ac82adff9a700e9549d250f3a1077997ba388 +2623ad17f5c1418892966d30897ec3a3c30b12cc +bd578b7ab6c52c28f14875f51cab9511b63b23f1 +80e3fdb791cf3f610b4c0fc3e27ac37498a8448a +32fa96d46d7383c83128f516d684bfaa8a54f821 +05f75b7c9427c0354f63639178676da0d67f938f +3f6565df6323534e69d797003d8cb20e99c2c255 +1c6a279fa81f27bcc469f988bcc20323e120e295 +9a72c800f6b6f43bc7a2f01821eedb2445474a04 +561c7853702f00a2480f211d6310a544f996a8b4 +351644024cb12f4f4868396599acf2fd0c743143 +1dbd8802f140a036bc203486e00086cdd0c42cee +f078d8264704513ca981d812b1ea3da415502300 +e505b812a243f79885a276589ee66437c41c6698 +02c2c5076bb72858d90bfe19bd10e93f258a94a6 +823a947bbf2a4bf63558cf0a4ed42056f5da3166 +ede4182c5202899231b47094112022fca0cddb3d +d9def518723fa76428b0f1ec19f50b4a4004c7b3 +5466906c7b1ed24f0c138803fd141c5b9f995e6f +ab1369a837c0e0868928c9c71fb00b0d2b64b075 +a7f86954a8dab604242616974cac3bfa5f0019a3 +67c133aa77c73f8090d63317138669b27397535e +f7425c9c3ee3efdf942febad90cde267ef5e7eae +4ec7fdf24b2c51bf6c3b22979b30829f4d3b910a +0573b87c9feafbe9687bc0966180e5a459700a4f +7f5acbdf1f34ec8ec8e1c5f69f720b43d4577509 +16d4ee2582155bddeaea29ef7d28e4b1dcd3b846 +55fff64fbec32e919656f2d0b4d1baf4ee6e981c +42a02b76e87254e1bc56b7443dd6a314b62ea52a +e6094d0aca3fc5fadfaffa7f4a638aaf87785300 +4b8937ab29e6750974e34cb0ec0265d62c5894e2 +0a1d9e2b491623a198068b3983b1cb37dd88ec41 +0d67436c908970edf44ec146aa793a2dc79ecf0d +49f36a67e8c2c4fa96647225975524ea70f7f72e +337780c89f1ed1712ce567ef1db2d10eae4c94b0 +6bde6b2bae8ef6109d068bf9c0d8b27551540d8c +1124052f9204fb4a8b867687bc9efc5fb2f3f8f5 +1734844e7c0e08475da28c41f13e9d581cb6e3e3 +562fc581d1f6297d09e4cb9f0c9e1ee61e29d29d +fb09f3463b38c1e5c80aa7eace515b52a25b2a78 +723e81c6636afdd6f1ea10f151630160c0a3860f +12a61edd46e87b59f2b50e2524b1a393b8a9ce2a +ea68fd540705a0efcaa5672a02bffaf48fe250b4 +83bf8451da70c1d1987ef9d864ee028364a25311 + + +# 2020 copyright year update +fc523c3ccff5b2227efe4391a68dae7a5b973971 +eaf495c3c42c322fcf774a4c2cf6c7e2d11e2647 +e7db75dbb16a15f03c74629e8b0f7c6ef3eed2f0 +9b38e8746835c677f60296617fcd651880efadac +2049527f03024970855ea3b3c1b10a5de8c462c2 + + +# 2021 copyright year update +f9968594206e538f13fa1c27c065027f10d4ea27 + + +# Use PEP 526 style type annotations (variable annotations) +6976c051ee1a356950ea0641fdebdfed51d10799 +dd24a4ef2dd6d72208469a03a7c5833340efb7b6 +aeb9e42d2be2b697879120b18a6380edf934e80b +1d4c414319598320f95eed245e4a2f9ad3e5a668 +035019629a8d67f83b1556f7d0ba06ea55f7a284 +555a52be82be3578470179f9047ed6abb943057e +7e6ea15b68960d809d742c18e0e9baa63a7d0d4c +000ae2e5000da9b9593560270398d8662f1e496d +b9f0582f06a8fe1b042333b9e8eb3cd575f1db2c +94dc1d78a44f40c497e0126ecb70a172615baa11 +eb68c237dddbceecb7a295642e51e4ac8a5b36c2 + + +# 2022 copyright year update +b84771dcd2fe1543acbdf87af3b60b323f41e80b +e023d1082d574d422ce50a8a99c8c012d6a21f92 + + +# Remove docstring titles and copyright & licence fields +6b8bccec5977f608f0b1e33f31a4888a2ea0d141 +4f5a3269a6053fe659093096d9b635a2c8e7e55e +5694e0ce60316b9cb9709d147e1a699ea9bde6da +6bb7b891a16fbcd5fad1f88fb472505549b9c084 +5775912455c25ee82734e1ff319a32f55946d79b +f05a068be980b7f237135596c9414e4737052681 + + +# 2023 copyright year update +a1c10f5d5e9734c6722d04b0b0781a5d88860745 + + +# Insert 'from __future__ import annotations' +f4c8a0a68e0013808d169357c9f77ebdf19d0f4e + + +# Use PEP 585 style type annotations (parameterised generics) +26f79b0d2dd88b353ac65623897bdfbe8bc07cab + + +# Use PEP 604 style type annotations ('X | Y' union types) +14a9289d780240bbce78ad3640e8e1b1b12df43f + + +# Change 'isort' profile +a13cf2c24dd16b37670ee1d359f511cbdfa4402d diff --git a/.github/workflows/builddoc.yml b/.github/workflows/builddoc.yml index bb24a82e4db..bcf6e91d80a 100644 --- a/.github/workflows/builddoc.yml +++ b/.github/workflows/builddoc.yml @@ -6,7 +6,7 @@ permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true jobs: @@ -20,9 +20,18 @@ jobs: with: python-version: 3 - name: Install dependencies - run: | + run: | sudo apt update sudo apt install -y graphviz - pip install -U tox - - name: Run Tox - run: tox -e docs + python -m pip install --upgrade pip + python -m pip install .[docs] + - name: Render the documentation + run: > + python + -X dev + -X warn_default_encoding + -m sphinx + -M html ./doc ./build/sphinx + -W + -n + --keep-going diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index 1db73578c9f..868a8c2c81c 100644 --- a/.github/workflows/coverage.yml +++ b/.github/workflows/coverage.yml @@ -5,6 +5,9 @@ on: [push] permissions: contents: read +env: + FORCE_COLOR: "1" + jobs: coverage: runs-on: ubuntu-latest @@ -24,12 +27,13 @@ jobs: run: sudo apt-get install graphviz - name: Install dependencies - run: python -m pip install -U pip tox pytest-cov + run: | + python -m pip install --upgrade pip + python -m pip install .[test] pytest-cov - - name: Run Tox - run: tox -e py -- -vv + - name: Test with pytest + run: python -m pytest -vv --cov . --cov-append --cov-config pyproject.toml env: - PYTEST_ADDOPTS: "--cov ./ --cov-append --cov-config pyproject.toml" VIRTUALENV_SYSTEM_SITE_PACKAGES: "1" - name: codecov diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml index b61d5598e72..857a6ede8fd 100644 --- a/.github/workflows/latex.yml +++ b/.github/workflows/latex.yml @@ -6,7 +6,7 @@ permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true jobs: @@ -16,7 +16,7 @@ jobs: container: image: ghcr.io/sphinx-doc/sphinx-ci env: - DO_EPUBCHECK: 1 + DO_EPUBCHECK: "1" steps: - name: Alias python3 to python run: ln -s /usr/bin/python3 /usr/bin/python @@ -24,6 +24,15 @@ jobs: - name: Check Python version run: python --version - name: Install dependencies - run: pip install -U pip tox - - name: Run Tox - run: tox -e py -- -vv + run: | + python -m pip install --upgrade pip + python -m pip install .[test] + - name: Test with pytest + run: > + python + -X dev + -X warn_default_encoding + -m pytest + -vv + --color yes + --durations 25 diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index f9a9f9ad43d..fb23ae1a927 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -6,16 +6,38 @@ permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true +env: + FORCE_COLOR: "1" + jobs: - build: + ruff: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3 + - name: Install pip + run: python -m pip install --upgrade pip + + - name: Install known good Ruff + run: python -m pip install ruff==0.0.261 + - name: Lint with known good Ruff + run: ruff . --diff --format github + + - name: Install latest Ruff + run: python -m pip install --upgrade ruff + - name: Lint with Ruff + continue-on-error: true + run: ruff . --diff --format github + + flake8: runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - tool: [docslint, flake8, isort, mypy, twine] steps: - uses: actions/checkout@v3 @@ -24,11 +46,13 @@ jobs: with: python-version: 3 - name: Install dependencies - run: python -m pip install -U tox pip - - name: Run Tox - run: tox -e ${{ matrix.tool }} + run: | + python -m pip install --upgrade pip + python -m pip install --upgrade "flake8>=3.5.0" "flake8-simplify" + - name: Lint with flake8 + run: flake8 . - ruff: + isort: runs-on: ubuntu-latest steps: @@ -38,8 +62,65 @@ jobs: with: python-version: 3 - name: Install dependencies - run: | + run: | python -m pip install --upgrade pip - python -m pip install --upgrade ruff - - name: Lint with Ruff - run: ruff . --diff --format github + python -m pip install --upgrade isort + - name: Lint with isort + run: isort --check-only --diff . + + mypy: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install --upgrade "mypy>=0.990" docutils-stubs types-requests + - name: Type check with mypy + run: mypy sphinx/ + + docs-lint: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install --upgrade sphinx-lint + - name: Lint documentation with sphinx-lint + run: > + sphinx-lint + --enable line-too-long + --max-line-length 85 + CHANGES + CONTRIBUTING.rst + README.rst + doc/ + + twine: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install --upgrade twine build + - name: Lint with twine + run: | + python -m build . + twine check dist/* diff --git a/.github/workflows/lock.yml b/.github/workflows/lock.yml index e24c068d12e..d86f4b36282 100644 --- a/.github/workflows/lock.yml +++ b/.github/workflows/lock.yml @@ -1,8 +1,8 @@ -name: 'Lock old threads' +name: Lock old threads on: schedule: - - cron: '0 0 * * *' + - cron: "0 0 * * *" permissions: issues: write @@ -16,5 +16,5 @@ jobs: - uses: dessant/lock-threads@v3 with: github-token: ${{ github.token }} - issue-inactive-days: '30' - pr-inactive-days: '30' + issue-inactive-days: "30" + pr-inactive-days: "30" diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ae2c7ab2774..8db64c118d0 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -6,13 +6,19 @@ permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true +env: + FORCE_COLOR: "1" + PYTHONDEVMODE: "1" # -X dev + PYTHONWARNDEFAULTENCODING: "1" # -X warn_default_encoding + PYTHONWARNINGS: "error,always:unclosed:ResourceWarning::" # default: all warnings as errors, except ResourceWarnings about unclosed items + jobs: ubuntu: runs-on: ubuntu-latest - name: Python ${{ matrix.python }} (${{ matrix.docutils }}) + name: Python ${{ matrix.python }} (Docutils ${{ matrix.docutils }}) strategy: fail-fast: false matrix: @@ -23,9 +29,8 @@ jobs: - "3.11" - "3.12-dev" docutils: - - "du18" - - "du19" - - "du-latest" + - "0.18" + - "0.19" steps: - uses: actions/checkout@v3 @@ -39,17 +44,35 @@ jobs: if: "endsWith(matrix.python, '-dev')" with: python-version: ${{ matrix.python }} + env: + PYTHONWARNINGS: "" - name: Check Python version run: python --version - name: Install graphviz run: sudo apt-get install graphviz - name: Install dependencies - run: python -m pip install -U pip tox - - name: Run Tox - run: tox -e ${{ matrix.docutils }} -- -vv + run: | + python -m pip install --upgrade pip + python -m pip install .[test] + env: + PYTHONWARNINGS: "" + - name: Install Docutils ${{ matrix.docutils }} + run: python -m pip install --upgrade "docutils==${{ matrix.docutils }}.*" + if: "!endsWith(matrix.python, '-dev')" + env: + PYTHONWARNINGS: "error,default:pkg_resources is deprecated:DeprecationWarning::,default:Deprecated call to `pkg_resources.declare_namespace:DeprecationWarning::" + - name: Install Docutils ${{ matrix.docutils }} (ignore warnings) + run: python -m pip install --upgrade "docutils==${{ matrix.docutils }}.*" + if: "endsWith(matrix.python, '-dev')" + env: + PYTHONWARNINGS: "" + - name: Test with pytest + run: python -m pytest -vv --durations 25 windows: runs-on: windows-2019 + name: Windows + steps: - uses: actions/checkout@v3 - name: Set up Python @@ -57,6 +80,37 @@ jobs: with: python-version: 3 - name: Install dependencies - run: python -m pip install -U pip tox - - name: Run Tox - run: tox -e py -- -vv + run: | + python -m pip install --upgrade pip + python -m pip install .[test] + env: + PYTHONWARNINGS: "" + - name: Test with pytest + run: python -m pytest -vv --durations 25 + + docutils-latest: + runs-on: ubuntu-latest + name: Docutils HEAD + + steps: + - uses: actions/checkout@v3 + - name: Set up Python 3 + uses: actions/setup-python@v4 + with: + python-version: "3" + - name: Check Python version + run: python --version + - name: Install graphviz + run: sudo apt-get install graphviz + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install .[test] + env: + PYTHONWARNINGS: "" + - name: Install Docutils' HEAD + run: python -m pip install git+https://repo.or.cz/docutils.git\#subdirectory=docutils + env: + PYTHONWARNINGS: "" + - name: Test with pytest + run: python -m pytest -vv diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index f66be63e50d..d021748578d 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -6,14 +6,14 @@ permissions: contents: read concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true jobs: build: runs-on: ubuntu-latest env: - node-version: 16 + node-version: "16" steps: - uses: actions/checkout@v3 @@ -24,6 +24,4 @@ jobs: cache: "npm" - run: npm install - name: Run headless test - uses: GabrielBB/xvfb-action@v1 - with: - run: npm test + run: xvfb-run -a npm test diff --git a/.github/workflows/transifex.yml b/.github/workflows/transifex.yml index 263622d02a1..da99f8c0049 100644 --- a/.github/workflows/transifex.yml +++ b/.github/workflows/transifex.yml @@ -1,8 +1,9 @@ -name: Sync translations on repository and transifex.com +name: Synchronise translations on: schedule: - - cron: "0 0 * * SUN" + # 22:38 GMT, every Sunday. Chosen to be a random time. + - cron: "38 22 * * SUN" workflow_dispatch: permissions: @@ -15,20 +16,23 @@ jobs: steps: - uses: actions/checkout@v3 - with: - ref: 5.x - name: Set up Python uses: actions/setup-python@v4 with: - python-version: 3.9 # https://github.com/transifex/transifex-client/pull/330 + python-version: 3 + - name: Install transifex client + run: | + mkdir -p /tmp/tx_cli && cd $_ + curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash + shell: bash - name: Install dependencies - run: pip install -U babel jinja2 transifex-client - - name: Install Sphinx - run: pip install . + run: pip install --upgrade babel jinja2 - name: Extract translations from source code - run: python utils/babel_runner.py extract + run: python utils/babel_runner.py extract - name: Push translations to transifex.com - run: cd sphinx/locale && tx push -s --no-interactive --parallel + run: | + cd sphinx/locale + /tmp/tx_cli/tx push --source --use-git-timestamps --workers 10 env: TX_TOKEN: ${{ secrets.TX_TOKEN }} @@ -41,28 +45,31 @@ jobs: steps: - uses: actions/checkout@v3 - with: - ref: 5.x - name: Set up Python uses: actions/setup-python@v4 with: - python-version: 3.9 # https://github.com/transifex/transifex-client/pull/330 + python-version: 3 + - name: Install transifex client + run: | + mkdir -p /tmp/tx_cli && cd $_ + curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash + shell: bash - name: Install dependencies - run: pip install -U babel jinja2 transifex-client - - name: Install Sphinx - run: pip install . + run: pip install --upgrade babel jinja2 - name: Extract translations from source code - run: python utils/babel_runner.py extract - - name: Pull translations to transifex.com - run: cd sphinx/locale && tx pull -a -f --no-interactive --parallel + run: python utils/babel_runner.py extract + - name: Pull translations from transifex.com + run: | + cd sphinx/locale + /tmp/tx_cli/tx pull --translations --all --force --use-git-timestamps --workers 10 env: TX_TOKEN: ${{ secrets.TX_TOKEN }} - name: Compile message catalogs - run: python utils/babel_runner.py compile + run: python utils/babel_runner.py compile - name: Create Pull Request uses: peter-evans/create-pull-request@v4 with: - commit-message: 'Update message catalogs' + commit-message: "[internationalisation] Update translations" branch: bot/pull-translations - title: Update message catalogs - labels: i18n + title: "[bot]: Update message catalogues" + labels: "internals:internationalisation" diff --git a/AUTHORS b/AUTHORS index a35c27044f0..786d28c70be 100644 --- a/AUTHORS +++ b/AUTHORS @@ -93,12 +93,3 @@ Contributors * Zac Hatfield-Dodds -- doctest reporting improvements, intersphinx performance Many thanks for all contributions! - -Included software -================= - -There are also a few modules or functions incorporated from other -authors and projects: - -* sphinx.util.jsdump uses the basestring encoding from simplejson, - written by Bob Ippolito, released under the MIT license diff --git a/CHANGES b/CHANGES index 96c0bdd1eed..55e75a042e8 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,142 @@ +Release 7.0.0 (released Apr 29, 2023) +===================================== + +Incompatible changes +-------------------- + +* #11359: Remove long-deprecated aliases for ``MecabSplitter`` and + ``DefaultSplitter`` in ``sphinx.search.ja``. +* #11360: Remove deprecated ``make_old_id`` functions in domain object + description classes. +* #11363: Remove the Setuptools integration (``build_sphinx`` hook in + ``setup.py``). +* #11364: Remove deprecated ``sphinx.ext.napoleon.iterators`` module. +* #11365: Remove support for the ``jsdump`` format in ``sphinx.search``. +* #11366: Make ``locale`` a required argument to + ``sphinx.util.i18n.format_date()``. +* #11370: Remove deprecated ``sphinx.util.stemmer`` module. +* #11371: Remove deprecated ``sphinx.pycode.ast.parse()`` function. +* #11372: Remove deprecated ``sphinx.io.read_doc()`` function. +* #11373: Removed deprecated ``sphinx.util.get_matching_files()`` function. +* #11378: Remove deprecated ``sphinx.util.docutils.is_html5_writer_available()`` + function. +* #11379: Make the ``env`` argument to ``Builder`` subclasses required. +* #11380: autosummary: Always emit grouped import exceptions. +* #11381: Remove deprecated ``style`` key for HTML templates. +* #11382: Remove deprecated ``sphinx.writers.latex.LaTeXTranslator.docclasses`` + attribute. +* #11383: Remove deprecated ``sphinx.builders.html.html5_ready`` and + ``sphinx.builders.html.HTMLTranslator`` attributes. +* #11385: Remove support for HTML 4 output. + +Release 6.2.1 (released Apr 25, 2023) +===================================== + +Bugs fixed +---------- + +* #11355: Revert the default type of :confval:`nitpick_ignore` and + :confval:`nitpick_ignore_regex` to ``list``. + +Release 6.2.0 (released Apr 23, 2023) +===================================== + +Dependencies +------------ + +* Require Docutils 0.18.1 or greater. + +Incompatible changes +-------------------- + +* LaTeX: removal of some internal TeX ``\dimen`` registers (not previously + publicly documented) as per 5.1.0 code comments in ``sphinx.sty``: + ``\sphinxverbatimsep``, ``\sphinxverbatimborder``, ``\sphinxshadowsep``, + ``\sphinxshadowsize``, and ``\sphinxshadowrule``. (refs: #11105) +* Remove ``.egg`` support from pycode ``ModuleAnalyser``; Python eggs are a + now-obsolete binary distribution format +* #11089: Remove deprecated code in ``sphinx.builders.linkcheck``. + Patch by Daniel Eades +* Remove internal-only ``sphinx.locale.setlocale`` + +Deprecated +---------- + +* #11247: Deprecate the legacy ``intersphinx_mapping`` format +* ``sphinx.util.osutil.cd`` is deprecated in favour of ``contextlib.chdir``. + +Features added +-------------- + +* #11277: :rst:dir:`autoproperty` allows the return type to be specified as + a type comment (e.g., ``# type: () -> int``). Patch by Bénédikt Tran +* #10811: Autosummary: extend ``__all__`` to imported members for template rendering + when option ``autosummary_ignore_module_all`` is set to ``False``. Patch by + Clement Pinard +* #11147: Add a ``content_offset`` parameter to ``nested_parse_with_titles()``, + allowing for correct line numbers during nested parsing. + Patch by Jeremy Maitin-Shepard +* Update to Unicode CLDR 42 +* Add a ``--jobs`` synonym for ``-j``. Patch by Hugo van Kemenade +* LaTeX: a command ``\sphinxbox`` for styling text elements with a (possibly + rounded) box, optional background color and shadow, has been added. + See :ref:`sphinxbox`. (refs: #11224) +* LaTeX: add ``\sphinxstylenotetitle``, ..., ``\sphinxstylewarningtitle``, ..., + for an extra layer of mark-up freeing up ``\sphinxstrong`` for other uses. + See :ref:`latex-macros`. (refs: #11267) +* LaTeX: :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip` can + now each be styled as the other admonitions, i.e. possibly with a background + color, individual border widths and paddings, possibly rounded corners, and + optional shadow. See :ref:`additionalcss`. (refs: #11234) +* LaTeX: admonitions and :dudir:`topic` (and + :dudir:`contents `) directives, and not only + :rst:dir:`code-block`, support ``box-decoration-break=slice``. +* LaTeX: let rounded boxes support up to 4 distinct border-widths (refs: #11243) +* LaTeX: new options ``noteTextColor``, ``noteTeXextras`` et al. + See :ref:`additionalcss`. +* LaTeX: support elliptical corners in rounded boxes. (refs: #11254) +* #11150: Include source location in highlighting warnings, when lexing fails. + Patch by Jeremy Maitin-Shepard +* #11281: Support for :confval:`imgmath_latex` ``= 'tectonic'`` or + ``= 'xelatex'``. Patch by Dimitar Dimitrov +* #11109, #9643: Add :confval:`python_display_short_literal_types` option for + condensed rendering of ``Literal`` types. + +Bugs fixed +---------- + +* #11079: LaTeX: figures with align attribute may disappear and strangely impact + following lists +* #11093: LaTeX: fix "multiply-defined references" PDF build warnings when one or + more reST labels directly precede an :rst:dir:`py:module` or :rst:dir:`automodule` + directive. Patch by Bénédikt Tran (picnixz) +* #11110: LaTeX: Figures go missing from latex pdf if their files have the same + base name and they use a post transform. Patch by aaron-cooper +* LaTeX: fix potential color leak from shadow to border of rounded boxes, if + shadow color is set but border color is not +* LaTeX: fix unintended 1pt upwards vertical shift of code blocks frames + respective to contents (when using rounded corners) +* #11235: LaTeX: added ``\color`` in topic (or admonition) contents may cause color + leak to the shadow and border at a page break +* #11264: LaTeX: missing space before colon after "Voir aussi" for :rst:dir:`seealso` + directive in French +* #11268: LaTeX: longtable with left alignment breaks out of current list + indentation context in PDF. Thanks to picnixz. +* #11274: LaTeX: external links are not properly escaped for ``\sphinxupquote`` + compatibility +* #11147: Fix source file/line number info in object description content and in + other uses of ``nested_parse_with_titles``. Patch by Jeremy Maitin-Shepard. +* #11192: Restore correct parallel search index building. + Patch by Jeremy Maitin-Shepard +* Use the new Transifex ``tx`` client + +Testing +-------- + +* Fail testing when any Python warnings are emitted +* Migrate remaining ``unittest.TestCase`` style test functions to pytest style +* Remove tests that rely on setuptools + Release 6.1.3 (released Jan 10, 2023) ===================================== @@ -20,10 +159,8 @@ Bugs fixed since Sphinx 5.1.0 * #11096: LaTeX: ``shadowsize`` key of sphinxsetup causes PDF build to crash since Sphinx 5.1.0 -* #11095: LaTeX: shadow of :dudir:`topic` and contents_ boxes not in page - margin since Sphinx 5.1.0 - - .. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents +* #11095: LaTeX: shadow of :dudir:`topic` and :dudir:`contents ` + boxes not in page margin since Sphinx 5.1.0 * #11100: Fix copying images when running under parallel mode. Release 6.1.1 (released Jan 05, 2023) @@ -377,7 +514,7 @@ Bugs fixed * #10498: gettext: TypeError is raised when sorting warning messages if a node has no line number. Patch by Adam Turner. -* #10493: HTML Theme: :rst:dir:`topic` directive is rendered incorrectly with +* #10493: HTML Theme: :dudir:`topic` directive is rendered incorrectly with Docutils 0.18. Patch by Adam Turner. * #10495: IndexError is raised for a :rst:role:`kbd` role having a separator. Patch by Adam Turner. @@ -481,7 +618,7 @@ Features added underscore.js) and modernised ``doctools.js`` and ``searchtools.js`` to EMCAScript 2018. Patch by Adam Turner. * #10302: C++, add support for conditional expressions (``?:``). -* #5157, #10251: Inline code is able to be highlighted via :rst:dir:`role` +* #5157, #10251: Inline code is able to be highlighted via :dudir:`role` directive * #10337: Make sphinx-build faster by caching Publisher object during build. Patch by Adam Turner. @@ -587,7 +724,7 @@ Bugs fixed * #9924: LaTeX: multi-line :rst:dir:`cpp:function` directive has big vertical spacing in Latexpdf * #10158: LaTeX: excessive whitespace since v4.4.0 for undocumented - variables/structure members + variables/structure members * #10175: LaTeX: named footnote reference is linked to an incorrect footnote if the name is also used in the different document * #10269: manpage: Failed to resolve the title of :rst:role:`ref` cross references @@ -762,7 +899,7 @@ Features added * #9672: More CSS classes on Python domain descriptions * #9695: More CSS classes on Javascript domain descriptions * #9683: Revert the removal of ``add_stylesheet()`` API. It will be kept until - the Sphinx-6.0 release + the Sphinx 6.0 release * #2068, add :confval:`intersphinx_disabled_reftypes` for disabling interphinx resolution of cross-references that do not have an explicit inventory specification. Specific types of cross-references can be disabled, @@ -804,7 +941,7 @@ Bugs fixed * #9697: py domain: An index entry with parens was registered for ``py:method`` directive with ``:property:`` option * #9775: py domain: Literal typehint was converted to a cross reference when - :confval:`autodoc_typehints='description'` + :confval:`autodoc_typehints`\ ``='description'`` * #9708: needs_extension failed to check double-digit version correctly * #9688: Fix Sphinx patched :dudir:`code` does not recognize ``:class:`` option * #9733: Fix for logging handler flushing warnings in the middle of the docs @@ -1097,7 +1234,8 @@ Incompatible changes 4.0.0b1 * #8539: autodoc: info-field-list is generated into the class description when - ``autodoc_typehints='description'`` and ``autoclass_content='class'`` set + :confval:`autodoc_typehints`\ ``='description'`` and + :confval:`autoclass_content`\ ``='class'`` set * #8898: extlinks: "%s" becomes required keyword in the link caption string * domain: The ``Index`` class becomes subclasses of ``abc.ABC`` to indicate methods that must be overridden in the concrete classes @@ -1359,7 +1497,7 @@ Features added functions in source code and keep them not evaluated for readability. * #8619: html: kbd role generates customizable HTML tags for compound keys * #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter - for :meth:`Sphinx.add_js_file()` and :meth:`Sphinx.add_css_file()` + for :meth:`.Sphinx.add_js_file()` and :meth:`.Sphinx.add_css_file()` * #6241: html: Allow to add JS/CSS files to the specific page when an extension calls ``app.add_js_file()`` or ``app.add_css_file()`` on :event:`html-page-context` event @@ -1373,7 +1511,7 @@ Features added * #8649: imgconverter: Skip availability check if builder supports the image type * #8573: napoleon: Allow to change the style of custom sections using - :confval:`napoleon_custom_styles` + :confval:`napoleon_custom_sections` * #8004: napoleon: Type definitions in Google style docstrings are rendered as references when :confval:`napoleon_preprocess_types` enabled * #6241: mathjax: Include mathjax.js only on the document using equations @@ -1460,7 +1598,7 @@ Bugs fixed inside function type signatures * #8780: LaTeX: long words in narrow columns may not be hyphenated * #8788: LaTeX: ``\titleformat`` last argument in sphinx.sty should be - bracketed, not braced (and is anyhow not needed) + bracketed, not braced (and is anyhow not needed) * #8849: LaTex: code-block printed out of margin (see the opt-in LaTeX syntax boolean :ref:`verbatimforcewraps ` for use via the :ref:`'sphinxsetup' ` key of ``latex_elements``) @@ -1560,7 +1698,7 @@ Features added messages when failed to resolve a cross-reference * #6914: Emit a detailed warning when failed to resolve a ``:ref:`` reference * #6629: linkcheck: The builder now handles rate limits. See - :confval:`linkcheck_retry_on_rate_limit` for details. + :confval:`linkcheck_rate_limit_timeout` for details. Bugs fixed ---------- @@ -1616,7 +1754,7 @@ Release 3.3.1 (released Nov 12, 2020) Bugs fixed ---------- -* #8372: autodoc: autoclass directive became slower than Sphinx-3.2 +* #8372: autodoc: autoclass directive became slower than Sphinx 3.2 * #7727: autosummary: raise PycodeError when documenting python package without __init__.py * #8350: autosummary: autosummary_mock_imports causes slow down builds @@ -1743,7 +1881,7 @@ Deprecated * ``sphinx.ext.autodoc.merge_special_members_option()`` * ``sphinx.writers.texinfo.TexinfoWriter.desc`` * C, parsing of pre-v3 style type directives and roles, along with the options - :confval:`c_allow_pre_v3` and :confval:`c_warn_on_allowed_pre_v3`. + :confval:`!c_allow_pre_v3` and :confval:`!c_warn_on_allowed_pre_v3`. Features added -------------- @@ -1762,7 +1900,7 @@ Features added * #7690: napoleon: parse type strings and make them hyperlinks as possible. The conversion rule can be updated via :confval:`napoleon_type_aliases` * #8049: napoleon: Create a hyperlink for each the type of parameter when - :confval:`napoleon_use_params` is False + :confval:`napoleon_use_param` is False * C, added :rst:dir:`c:alias` directive for inserting copies of existing declarations. * #7745: html: inventory is broken if the docname contains a space @@ -1780,9 +1918,9 @@ Features added and the ``:noindex:`` option. * #7899: C, add possibility of parsing of some pre-v3 style type directives and roles and try to convert them to equivalent v3 directives/roles. - Set the new option :confval:`c_allow_pre_v3` to ``True`` to enable this. + Set the new option :confval:`!c_allow_pre_v3` to ``True`` to enable this. The warnings printed from this functionality can be suppressed by setting - :confval:`c_warn_on_allowed_pre_v3`` to ``True``. + :confval:`!c_warn_on_allowed_pre_v3` to ``True``. The functionality is immediately deprecated. * #7999: C, add support for named variadic macro arguments. * #8071: Allow to suppress "self referenced toctrees" warning @@ -1813,7 +1951,7 @@ Bugs fixed * #4258: napoleon: decorated special methods are not shown * #7799: napoleon: parameters are not escaped for combined params in numpydoc * #7780: napoleon: multiple parameters declaration in numpydoc was wrongly - recognized when napoleon_use_params=True + recognized when ``napoleon_use_param=True`` * #7715: LaTeX: ``numfig_secnum_depth > 1`` leads to wrong figure links * #7846: html theme: XML-invalid files were generated * #7894: gettext: Wrong source info is shown when using rst_epilog @@ -1981,8 +2119,8 @@ Features added * C++, parse parameterized noexcept specifiers. * #7294: C++, parse expressions with user-defined literals. * C++, parse trailing return types. -* #7143: py domain: Add ``:final:`` option to :rst:dir:`py:class:`, - :rst:dir:`py:exception:` and :rst:dir:`py:method:` directives +* #7143: py domain: Add ``:final:`` option to :rst:dir:`py:class`, + :rst:dir:`py:exception` and :rst:dir:`py:method` directives * #7596: py domain: Change a type annotation for variables to a hyperlink * #7770: std domain: :rst:dir:`option` directive support arguments in the form of ``foo[=bar]`` @@ -2006,7 +2144,7 @@ Bugs fixed * #7559: autodoc: misdetects a sync function is async * #6857: autodoc: failed to detect a classmethod on Enum class * #7562: autodoc: a typehint contains spaces is wrongly rendered under - autodoc_typehints='description' mode + :confval:`autodoc_typehints`\ ``='description'`` mode * #7551: autodoc: failed to import nested class * #7362: autodoc: does not render correct signatures for built-in functions * #7654: autodoc: ``Optional[Union[foo, bar]]`` is presented as @@ -2109,7 +2247,7 @@ Release 3.0.1 (released Apr 11, 2020) Incompatible changes -------------------- -* #7418: std domain: :rst:dir:`term` role becomes case sensitive +* #7418: std domain: :rst:role:`term` role becomes case sensitive Bugs fixed ---------- @@ -2120,8 +2258,8 @@ Bugs fixed * #7418: std domain: duplication warning for glossary terms is case insensitive * #7438: C++, fix merging overloaded functions in parallel builds. * #7422: autodoc: fails with ValueError when using autodoc_mock_imports -* #7435: autodoc: ``autodoc_typehints='description'`` doesn't suppress typehints - in signature for classes/methods +* #7435: autodoc: :confval:`autodoc_typehints`\ ``='description'`` doesn't + suppress typehints in signature for classes/methods * #7451: autodoc: fails with AttributeError when an object returns non-string object as a ``__doc__`` member * #7423: crashed when giving a non-string object to logger @@ -2430,7 +2568,7 @@ Features added * #6418: autodoc: Add a new extension ``sphinx.ext.autodoc.typehints``. It shows typehints as object description if ``autodoc_typehints = "description"`` set. This is an experimental extension and it will be integrated into autodoc core - in Sphinx-3.0 + in Sphinx 3.0 * SphinxTranslator now calls visitor/departure method for super node class if visitor/departure method for original node class not found * #6418: Add new event: :event:`object-description-transform` @@ -2532,7 +2670,7 @@ Features added authentication information when doing ``linkcheck`` builds * #6872: linkcheck: Handles HTTP 308 Permanent Redirect * #6613: html: Wrap section number in span tag -* #6781: gettext: Add :confval:`gettext_last_translator' and +* #6781: gettext: Add :confval:`gettext_last_translator` and :confval:`gettext_language_team` to customize headers of POT file Bugs fixed @@ -2671,7 +2809,7 @@ Bugs fixed since Sphinx 1.8.0 (refs: #6533) * #6531: Failed to load last environment object when extension added * #736: Invalid sort in pair index -* #6527: :confval:`last_updated` wrongly assumes timezone as UTC +* #6527: :data:`last_updated` wrongly assumes timezone as UTC * #5592: std domain: :rst:dir:`option` directive registers an index entry for each comma separated option * #6549: sphinx-build: Escaped characters in error messages @@ -2725,7 +2863,7 @@ Incompatible changes * #4550: html: Centering tables by default using CSS * #6239: latex: xelatex and xeCJK are used for Chinese documents by default * ``Sphinx.add_lexer()`` now takes a Lexer class instead of instance. An - instance of lexers are still supported until Sphinx-3.x. + instance of lexers are still supported until Sphinx 3.x. Deprecated ---------- @@ -2786,7 +2924,7 @@ Features added - ``PythonDomain.note_object()`` - ``SphinxDirective.set_source_info()`` -* #6180: Support ``--keep-going`` with BuildDoc setup command +* #6180: Support ``--keep-going`` with ``BuildDoc`` setup command * ``math`` directive now supports ``:class:`` option * todo: ``todo`` directive now supports ``:name:`` option * Enable override via environment of ``SPHINXOPTS`` and ``SPHINXBUILD`` Makefile @@ -2816,7 +2954,7 @@ Features added - ``:property:`` - ``:staticmethod:`` -* rst domain: Add :rst:dir:`directive:option` directive to describe the option +* rst domain: Add :rst:dir:`rst:directive:option` directive to describe the option for directive * #6306: html: Add a label to search form for accessability purposes * #4390: html: Consistent and semantic CSS for signatures @@ -2863,9 +3001,9 @@ Bugs fixed * RemovedInSphinx30Warning is marked as pending * deprecation warnings are not emitted - - sphinx.application.CONFIG_FILENAME - - sphinx.builders.htmlhelp - - :confval:`viewcode_import` + - ``sphinx.application.CONFIG_FILENAME`` + - ``sphinx.builders.htmlhelp`` + - :confval:`!viewcode_import` * #6208: C++, properly parse full xrefs that happen to have a short xref as prefix @@ -3348,7 +3486,7 @@ Incompatible changes 1.8.0b1 -* #5156: the :py:mod:`sphinx.ext.graphviz: extension runs `dot` in the +* #5156: the :py:mod:`sphinx.ext.graphviz` extension runs ``dot`` in the directory of the document being built instead of in the root directory of the documentation. * #4460: extensions which stores any data to environment should return the @@ -3373,7 +3511,7 @@ Incompatible changes * #4811: The files under :confval:`html_static_path` are excluded from source files. * latex: Use ``\sphinxcite`` for citation references instead ``\hyperref`` -* The config value ``viewcode_import`` is renamed to +* The config value :confval:`!viewcode_import` is renamed to :confval:`viewcode_follow_imported_members` (refs: #4035) * #1857: latex: :confval:`latex_show_pagerefs` does not add pagerefs for citations @@ -3414,7 +3552,7 @@ Deprecated * :confval:`autodoc_default_flags` is deprecated * quickstart: ``--epub`` option becomes default, so it is deprecated * Drop function based directive support. For now, Sphinx only supports class - based directives (see :class:`~Directive`) + based directives (see :class:`~docutils.parsers.rst.Directive`) * ``sphinx.util.docutils.directive_helper()`` is deprecated * ``sphinx.cmdline`` is deprecated * ``sphinx.make_mode`` is deprecated @@ -3917,7 +4055,7 @@ Deprecated * ``format_annotation()`` and ``formatargspec()`` is deprecated. Please use ``sphinx.util.inspect.Signature`` instead. * ``sphinx.ext.autodoc.AutodocReporter`` is replaced by ``sphinx.util.docutils. - switch_source_input()`` and now deprecated. It will be removed in Sphinx-2.0. + switch_source_input()`` and now deprecated. It will be removed in Sphinx 2.0. * ``sphinx.ext.autodoc.add_documenter()`` and ``AutoDirective._register`` is now deprecated. Please use ``app.add_autodocumenter()`` instead. * ``AutoDirective._special_attrgetters`` is now deprecated. Please use @@ -3990,8 +4128,8 @@ Features removed * Configuration variables - - html_use_smartypants - - latex_keep_old_macro_names + - :confval:`!html_use_smartypants` + - :confval:`!latex_keep_old_macro_names` - latex_elements['footer'] * utility methods of ``sphinx.application.Sphinx`` class @@ -4133,7 +4271,7 @@ Bugs fixed * #4281: Race conditions when creating output directory * #4315: For PDF 'howto' documents, ``latex_toplevel_sectioning='part'`` generates ``\chapter`` commands -* #4214: Two todolist directives break sphinx-1.6.5 +* #4214: Two todolist directives break Sphinx 1.6.5 * Fix links to external option docs with intersphinx (refs: #3769) * #4091: Private members not documented without :undoc-members: @@ -4317,7 +4455,7 @@ Incompatible changes option and other options (refs: #3416) * LuaLaTeX engine uses ``fontspec`` like XeLaTeX. It is advised ``latex_engine = 'lualatex'`` be used only on up-to-date TeX installs (refs #3070, #3466) -* :confval:`latex_keep_old_macro_names` default value has been changed from +* :confval:`!latex_keep_old_macro_names` default value has been changed from ``True`` to ``False``. This means that some LaTeX macros for styling are by default defined only with ``\sphinx..`` prefixed names. (refs: #3429) * Footer "Continued on next page" of LaTeX longtable's now not framed (refs: @@ -4523,13 +4661,13 @@ Deprecated * latex package ``footnote`` is not loaded anymore by its bundled replacement ``footnotehyper-sphinx``. The redefined macros keep the same names as in the original package. -* #3429: deprecate config setting ``latex_keep_old_macro_names``. It will be - removed at 1.7, and already its default value has changed from ``True`` to +* #3429: deprecate config setting :confval:`!latex_keep_old_macro_names`. It will + be removed at 1.7, and already its default value has changed from ``True`` to ``False``. * #3221: epub2 builder is deprecated * #3254: ``sphinx.websupport`` is now separated into independent package; ``sphinxcontrib-websupport``. ``sphinx.websupport`` will be removed in - Sphinx-2.0. + Sphinx 2.0. * #3628: ``sphinx_themes`` entry_point is deprecated. Please use ``sphinx.html_themes`` instead. @@ -4790,7 +4928,7 @@ Incompatible changes * Fix ``epub`` and ``epub3`` builders that contained links to ``genindex`` even if ``epub_use_index = False``. * ``html_translator_class`` is now deprecated. - Use `Sphinx.set_translator()` API instead. + Use :meth:`~sphinx.application.Sphinx.set_translator` API instead. * Drop python 2.6 and 3.3 support * Drop epub3 builder's ``epub3_page_progression_direction`` option (use ``epub3_writing_mode``). @@ -4824,7 +4962,7 @@ Incompatible changes Deprecated ---------- -These features are removed in Sphinx-1.6: +These features are removed in Sphinx 1.6: * LDML format support in i18n feature * ``sphinx.addnodes.termsep`` @@ -5149,7 +5287,7 @@ Incompatible changes Features added -------------- -* new config option ``latex_keep_old_macro_names``, defaults to True. If False, +* new config option :confval:`!latex_keep_old_macro_names`, defaults to True. If False, lets macros (for text styling) be defined only with ``\sphinx``-prefixed names * latex writer allows user customization of "shadowed" boxes (topics), via three length variables. @@ -5173,7 +5311,7 @@ Bugs fixed namespaces. * latex, images (from image directive) in lists or quoted blocks did not obey indentation (fixed together with #2671) -* #2733: since Sphinx-1.4.4 ``make latexpdf`` generates lots of hyperref +* #2733: since Sphinx 1.4.4 ``make latexpdf`` generates lots of hyperref warnings * #2731: `sphinx.ext.autodoc` does not access propertymethods which raises any exceptions @@ -5333,7 +5471,7 @@ Incompatible changes * The default format of `today_fmt` and `html_last_updated_fmt` is back to strftime format again. Locale Date Markup Language is also supported for - backward compatibility until Sphinx-1.5. + backward compatibility until Sphinx 1.5. Translations ------------ @@ -5399,8 +5537,8 @@ Incompatible changes `_ like ``"MMMM dd, YYYY"`` is default format for `today_fmt` and `html_last_updated_fmt`. However strftime format like ``"%B %d, %Y"`` is also - supported for backward compatibility until Sphinx-1.5. Later format will be - disabled from Sphinx-1.5. + supported for backward compatibility until Sphinx 1.5. Later format will be + disabled from Sphinx 1.5. * #2327: ``latex_use_parts`` is deprecated now. Use `latex_toplevel_sectioning` instead. * #2337: Use ``\url{URL}`` macro instead of ``\href{URL}{URL}`` in LaTeX writer. @@ -5697,7 +5835,7 @@ Bugs fixed * Fix a crash when setting up extensions which do not support metadata. * #1784: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js`` * #1822, #1892: Fix regression for #1061. autosummary can't generate doc for - imported members since sphinx-1.3b3. Thanks to Eric Larson. + imported members since Sphinx 1.3b3. Thanks to Eric Larson. * #1793, #1819: "see also" misses a linebreak in text output. Thanks to Takayuki Hirai. * #1780, #1866: "make text" shows "class" keyword twice. Thanks to Takayuki @@ -5730,7 +5868,7 @@ Bugs fixed node.astext() during docutils transforming. * #1989: "make blahblah" on Windows indicate help messages for sphinx-build every time. It was caused by wrong make.bat that generated by - Sphinx-1.3.0/1.3.1. + Sphinx 1.3.0/1.3.1. * On Py2 environment, conf.py that is generated by sphinx-quickstart should have u prefixed config value for 'version' and 'release'. * #2102: On Windows + Py3, using ``|today|`` and non-ASCII date format will @@ -6103,7 +6241,7 @@ Bugs fixed * PR#297, #1571: Add imgpath property to all builders. It make easier to develop builder extensions. Thanks to Takeshi Komiya. * #1584: Point to master doc in HTML "top" link. -* #1585: Autosummary of modules broken in Sphinx-1.2.3. +* #1585: Autosummary of modules broken in Sphinx 1.2.3. * #1610: Sphinx cause AttributeError when MeCab search option is enabled and python-mecab is not installed. * #1674: Do not crash if a module's ``__all__`` is not a list of strings. @@ -6132,7 +6270,7 @@ Bugs fixed * #636: Keep straight single quotes in literal blocks in the LaTeX build. * #1419: Generated i18n sphinx.js files are missing message catalog entries - from '.js_t' and '.html'. The issue was introduced from Sphinx-1.1 + from '.js_t' and '.html'. The issue was introduced from Sphinx 1.1 * #1363: Fix i18n: missing python domain's cross-references with currentmodule directive or currentclass directive. * #1444: autosummary does not create the description from attributes docstring. @@ -6160,7 +6298,7 @@ Bugs fixed * #1477: gettext does not extract nodes.line in a table or list. * #1544: ``make text`` generates wrong table when it has empty table cells. * #1522: Footnotes from table get displayed twice in LaTeX. This problem has - been appeared from Sphinx-1.2.1 by #949. + been appeared from Sphinx 1.2.1 by #949. * #508: Sphinx every time exit with zero when is invoked from setup.py command. ex. ``python setup.py build_sphinx -b doctest`` return zero even if doctest failed. @@ -6537,7 +6675,8 @@ Features added * Other builders: - Added the Docutils-native XML and pseudo-XML builders. See - :class:`XMLBuilder` and :class:`PseudoXMLBuilder`. + :class:`~sphinx.builders.xml.XMLBuilder` and + :class:`~sphinx.builders.xml.PseudoXMLBuilder`. - PR#45: The linkcheck builder now checks ``#anchor``\ s for existence. - PR#123, #1106: Add `epub_use_index` configuration value. If provided, it will be used instead of `html_use_index` for epub @@ -6804,26 +6943,26 @@ Features added * Other builders: - - #516: Added new value of the `latex_show_urls` option to + - #516: Added new value of the :confval:`latex_show_urls` option to show the URLs in footnotes. - - #209: Added `text_newlines` and `text_sectionchars` + - #209: Added :confval:`text_newlines` and :confval:`text_sectionchars` config values. - - Added `man_show_urls` config value. + - Added :confval:`man_show_urls` config value. - #472: linkcheck builder: Check links in parallel, use HTTP HEAD requests and allow configuring the timeout. New config values: - `linkcheck_timeout` and `linkcheck_workers`. - - #521: Added `linkcheck_ignore` config value. + :confval:`linkcheck_timeout` and :confval:`linkcheck_workers`. + - #521: Added :confval:`linkcheck_ignore` config value. - #28: Support row/colspans in tables in the LaTeX builder. * Configuration and extensibility: - - #537: Added `nitpick_ignore`. + - #537: Added :confval:`nitpick_ignore`. - #306: Added :event:`env-get-outdated` event. - - :meth:`.Application.add_stylesheet` now accepts full URIs. + - :meth:`!Application.add_stylesheet` now accepts full URIs. * Autodoc: - - #564: Add `autodoc_docstring_signature`. When enabled (the + - #564: Add :confval:`autodoc_docstring_signature`. When enabled (the default), autodoc retrieves the signature from the first line of the docstring, if it is found there. - #176: Provide ``private-members`` option for autodoc directives. @@ -7083,7 +7222,7 @@ Release 1.0.2 (Aug 14, 2010) ============================ * #490: Fix cross-references to objects of types added by the - :func:`~.Sphinx.add_object_type` API function. + :func:`~sphinx.application.Sphinx.add_object_type` API function. * Fix handling of doc field types for different directive types. @@ -7155,7 +7294,7 @@ Incompatible changes * The old markup for defining and linking to C directives is now deprecated. It will not work anymore in future versions without - activating the :mod:`~sphinx.ext.oldcmarkup` extension; in Sphinx + activating the ``oldcmarkup`` extension; in Sphinx 1.0, it is activated by default. * Removed support for old dependency versions; requirements are now: @@ -7264,7 +7403,7 @@ Features added - Added `needs_sphinx` config value and :meth:`~sphinx.application.Sphinx.require_sphinx` application API method. - - #200: Added :meth:`~sphinx.application.Sphinx.add_stylesheet` + - #200: Added :meth:`!add_stylesheet` application API method. * Extensions: @@ -7304,9 +7443,1250 @@ Features added "striptags" Jinja filter. -Previous versions -================= +Release 0.6.7 (Jun 05, 2010) +============================ + +* #440: Remove usage of a Python >= 2.5 API in the ``literalinclude`` + directive. + +* Fix a bug that prevented some references being generated in the + LaTeX builder. + +* #428: Add some missing CSS styles for standard docutils classes. + +* #432: Fix UnicodeErrors while building LaTeX in translated locale. + + +Release 0.6.6 (May 25, 2010) +============================ + +* Handle raw nodes in the ``text`` writer. + +* Fix a problem the Qt help project generated by the ``qthelp`` + builder that would lead to no content being displayed in the Qt + Assistant. + +* #393: Fix the usage of Unicode characters in mathematic formulas + when using the ``pngmath`` extension. + +* #404: Make ``\and`` work properly in the author field of the + ``latex_documents`` setting. + +* #409: Make the ``highlight_language`` config value work properly + in the LaTeX builder. + +* #418: Allow relocation of the translation JavaScript files to + the system directory on Unix systems. + +* #414: Fix handling of Windows newlines in files included with + the ``literalinclude`` directive. + +* #377: Fix crash in linkcheck builder. + +* #387: Fix the display of search results in ``dirhtml`` output. + +* #376: In autodoc, fix display of parameter defaults containing + backslashes. + +* #370: Fix handling of complex list item labels in LaTeX output. + +* #374: Make the ``doctest_path`` config value of the doctest + extension actually work. + +* Fix the handling of multiple toctrees when creating the global + TOC for the ``toctree()`` template function. + +* Fix the handling of hidden toctrees when creating the global TOC + for the ``toctree()`` template function. + +* Fix the handling of nested lists in the text writer. + +* #362: In autodoc, check for the existence of ``__self__`` on + function objects before accessing it. + +* #353: Strip leading and trailing whitespace when extracting + search words in the search function. + + +Release 0.6.5 (Mar 01, 2010) +============================ + +* In autodoc, fix the omission of some module members explicitly + documented using documentation comments. + +* #345: Fix cropping of sidebar scroll bar with ``stickysidebar`` + option of the default theme. + +* #341: Always generate UNIX newlines in the quickstart Makefile. + +* #338: Fix running with ``-C`` under Windows. + +* In autodoc, allow customizing the signature of an object where + the built-in mechanism fails. + +* #331: Fix output for enumerated lists with start values in LaTeX. + +* Make the ``start-after`` and ``end-before`` options to the + ``literalinclude`` directive work correctly if not used together. + +* #321: Fix link generation in the LaTeX builder. + + +Release 0.6.4 (Jan 12, 2010) +============================ + +* Improve the handling of non-Unicode strings in the configuration. + +* #316: Catch OSErrors occurring when calling graphviz with + arguments it doesn't understand. + +* Restore compatibility with Pygments >= 1.2. + +* #295: Fix escaping of hyperref targets in LaTeX output. + +* #302: Fix links generated by the ``:doc:`` role for LaTeX output. + +* #286: collect todo nodes after the whole document has been read; + this allows placing substitution references in todo items. + +* #294: do not ignore an explicit ``today`` config value in a + LaTeX build. + +* The ``alt`` text of inheritance diagrams is now much cleaner. + +* Ignore images in section titles when generating link captions. + +* #310: support exception messages in the ``testoutput`` blocks of + the ``doctest`` extension. + +* #293: line blocks are styled properly in HTML output. + +* #285: make the ``locale_dirs`` config value work again. + +* #303: ``html_context`` values given on the command line via ``-A`` + should not override other values given in conf.py. + +* Fix a bug preventing incremental rebuilds for the ``dirhtml`` + builder. + +* #299: Fix the mangling of quotes in some literal blocks. + +* #292: Fix path to the search index for the ``dirhtml`` builder. + +* Fix a Jython compatibility issue: make the dependence on the + ``parser`` module optional. + +* #238: In autodoc, catch all errors that occur on module import, + not just ``ImportError``. + +* Fix the handling of non-data, but non-method descriptors in autodoc. + +* When copying file times, ignore OSErrors raised by ``os.utime()``. + + +Release 0.6.3 (Sep 03, 2009) +============================ + +* Properly add C module filenames as dependencies in autodoc. + +* #253: Ignore graphviz directives without content instead of + raising an unhandled exception. + +* #241: Fix a crash building LaTeX output for documents that contain + a todolist directive. + +* #252: Make it easier to change the build dir in the Makefiles + generated by quickstart. + +* #220: Fix CSS so that displaymath really is centered. + +* #222: Allow the "Footnotes" header to be translated. + +* #225: Don't add whitespace in generated HTML after inline tags. + +* #227: Make ``literalinclude`` work when the document's path + name contains non-ASCII characters. + +* #229: Fix autodoc failures with members that raise errors + on ``getattr()``. + +* #205: When copying files, don't copy full stat info, only + modification times. + +* #232: Support non-ASCII metadata in Qt help builder. + +* Properly format bullet lists nested in definition lists for LaTeX. + +* Section titles are now allowed inside ``only`` directives. + +* #201: Make ``centered`` directive work in LaTeX output. + +* #206: Refuse to overwrite an existing master document in + sphinx-quickstart. + +* #208: Use MS-sanctioned locale settings, determined by the + ``language`` config option, in the HTML help builder. + +* #210: Fix nesting of HTML tags for displayed math from pngmath + extension. + +* #213: Fix centering of images in LaTeX output. + +* #211: Fix compatibility with docutils 0.5. + + +Release 0.6.2 (Jun 16, 2009) +============================ + +* #130: Fix obscure IndexError in doctest extension. + +* #167: Make glossary sorting case-independent. + +* #196: Add a warning if an extension module doesn't have a + ``setup()`` function. + +* #158: Allow '..' in template names, and absolute template paths; + Jinja 2 by default disables both. + +* When highlighting Python code, ignore extra indentation before + trying to parse it as Python. + +* #191: Don't escape the tilde in URIs in LaTeX. + +* Don't consider contents of source comments for the search index. + +* Set the default encoding to ``utf-8-sig`` to handle files with a + UTF-8 BOM correctly. + +* #178: apply ``add_function_parentheses`` config value to C + functions as promised. + +* #173: Respect the docutils ``title`` directive. + +* #172: The ``obj`` role now links to modules as promised. + +* #19: Tables now can have a "longtable" class, in order to get + correctly broken into pages in LaTeX output. + +* Look for Sphinx message catalogs in the system default path before + trying ``sphinx/locale``. + +* Fix the search for methods via "classname.methodname". + +* #155: Fix Python 2.4 compatibility: exceptions are old-style + classes there. + +* #150: Fix display of the "sphinxdoc" theme on Internet Explorer + versions 6 and 7. + +* #146: Don't fail to generate LaTeX when the user has an active + ``.docutils`` configuration. + +* #29: Don't generate visible "-{-}" in option lists in LaTeX. + +* Fix cross-reference roles when put into substitutions. + +* Don't put image "alt" text into table-of-contents entries. + +* In the LaTeX writer, do not raise an exception on too many section + levels, just use the "subparagraph" level for all of them. + +* #145: Fix autodoc problem with automatic members that refuse to be + getattr()'d from their parent. + +* If specific filenames to build are given on the command line, + check that they are within the source directory. + +* Fix autodoc crash for objects without a ``__name__``. + +* Fix intersphinx for installations without urllib2.HTTPSHandler. + +* #134: Fix pending_xref leftover nodes when using the todolist + directive from the todo extension. + + +Release 0.6.1 (Mar 26, 2009) +============================ + +* #135: Fix problems with LaTeX output and the graphviz extension. + +* #132: Include the autosummary "module" template in the distribution. + + +Release 0.6 (Mar 24, 2009) +========================== + +New features added +------------------ + +* Incompatible changes: + + - Templating now requires the Jinja2 library, which is an enhanced + version of the old Jinja1 engine. Since the syntax and semantic + is largely the same, very few fixes should be necessary in + custom templates. + + - The "document" div tag has been moved out of the ``layout.html`` + template's "document" block, because the closing tag was already + outside. If you overwrite this block, you need to remove your + "document" div tag as well. + + - The ``autodoc_skip_member`` event now also gets to decide + whether to skip members whose name starts with underscores. + Previously, these members were always automatically skipped. + Therefore, if you handle this event, add something like this + to your event handler to restore the old behavior:: + + if name.startswith('_'): + return True + +* Theming support, see the new section in the documentation. + +* Markup: + + - Due to popular demand, added a ``:doc:`` role which directly + links to another document without the need of creating a + label to which a ``:ref:`` could link to. + + - #4: Added a ``:download:`` role that marks a non-document file + for inclusion into the HTML output and links to it. + + - Added an ``only`` directive that can selectively include text + based on enabled "tags". Tags can be given on the command + line. Also, the current builder output format (e.g. "html" or + "latex") is always a defined tag. + + - #10: Added HTML section numbers, enabled by giving a + ``:numbered:`` flag to the ``toctree`` directive. + + - #114: Added an ``abbr`` role to markup abbreviations and + acronyms. + + - The ``literalinclude`` directive now supports several more + options, to include only parts of a file. + + - The ``toctree`` directive now supports a ``:hidden:`` flag, + which will prevent links from being generated in place of + the directive -- this allows you to define your document + structure, but place the links yourself. + + - #123: The ``glossary`` directive now supports a ``:sorted:`` + flag that sorts glossary entries alphabetically. + + - Paths to images, literal include files and download files + can now be absolute (like ``/images/foo.png``). They are + treated as relative to the top source directory. + + - #52: There is now a ``hlist`` directive, creating a compact + list by placing distributing items into multiple columns. + + - #77: If a description environment with info field list only + contains one ``:param:`` entry, no bullet list is generated. + + - #6: Don't generate redundant ``
    `` for top-level TOC tree + items, which leads to a visual separation of TOC entries. + + - #23: Added a ``classmethod`` directive along with ``method`` + and ``staticmethod``. + + - Scaled images now get a link to the unscaled version. + + - SVG images are now supported in HTML (via ```` and + ```` tags). + + - Added a ``toctree`` callable to the templates, and the ability + to include external links in toctrees. The 'collapse' keyword + argument indicates whether or not to only display subitems of + the current page. (Defaults to True.) + +* Configuration: + + - The new config value ``rst_epilog`` can contain reST that is + appended to each source file that is read. This is the right + place for global substitutions. + + - The new ``html_add_permalinks`` config value can be used to + switch off the generated "paragraph sign" permalinks for each + heading and definition environment. + + - The new ``html_show_sourcelink`` config value can be used to + switch off the links to the reST sources in the sidebar. + + - The default value for ``htmlhelp_basename`` is now the project + title, cleaned up as a filename. + + - The new ``modindex_common_prefix`` config value can be used to + ignore certain package names for module index sorting. + + - The new ``trim_footnote_reference_space`` config value mirrors + the docutils config value of the same name and removes the + space before a footnote reference that is necessary for reST + to recognize the reference. + + - The new ``latex_additional_files`` config value can be used to + copy files (that Sphinx doesn't copy automatically, e.g. if they + are referenced in custom LaTeX added in ``latex_elements``) to + the build directory. + +* Builders: + + - The HTML builder now stores a small file named ``.buildinfo`` in + its output directory. It stores a hash of config values that + can be used to determine if a full rebuild needs to be done (e.g. + after changing ``html_theme``). + + - New builder for Qt help collections, by Antonio Valentino. + + - The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates + a separate directory for every page, and places the page there + in a file called ``index.html``. Therefore, page URLs and links + don't need to contain ``.html``. + + - The new ``html_link_suffix`` config value can be used to select + the suffix of generated links between HTML files. + + - #96: The LaTeX builder now supports figures wrapped by text, when + using the ``figwidth`` option and right/left alignment. + +* New translations: + + - Italian by Sandro Dentella. + - Ukrainian by Petro Sasnyk. + - Finnish by Jukka Inkeri. + - Russian by Alexander Smishlajev. + +* Extensions and API: + + - New ``graphviz`` extension to embed graphviz graphs. + + - New ``inheritance_diagram`` extension to embed... inheritance + diagrams! + + - New ``autosummary`` extension that generates summaries of + modules and automatic documentation of modules. + + - Autodoc now has a reusable Python API, which can be used to + create custom types of objects to auto-document (e.g. Zope + interfaces). See also ``Sphinx.add_autodocumenter()``. + + - Autodoc now handles documented attributes. + + - Autodoc now handles inner classes and their methods. + + - Autodoc can document classes as functions now if explicitly + marked with ``autofunction``. + + - Autodoc can now exclude single members from documentation + via the ``exclude-members`` option. + + - Autodoc can now order members either alphabetically (like + previously) or by member type; configurable either with the + config value ``autodoc_member_order`` or a ``member-order`` + option per directive. + + - The function ``Sphinx.add_directive()`` now also supports + docutils 0.5-style directive classes. If they inherit from + ``sphinx.util.compat.Directive``, they also work with + docutils 0.4. + + - There is now a ``Sphinx.add_lexer()`` method to be able to use + custom Pygments lexers easily. + + - There is now ``Sphinx.add_generic_role()`` to mirror the + docutils' own function. + +* Other changes: + + - Config overrides for single dict keys can now be given on the + command line. + + - There is now a ``doctest_global_setup`` config value that can + be used to give setup code for all doctests in the documentation. + + - Source links in HTML are now generated with ``rel="nofollow"``. + + - Quickstart can now generate a Windows ``make.bat`` file. + + - #62: There is now a ``-w`` option for sphinx-build that writes + warnings to a file, in addition to stderr. + + - There is now a ``-W`` option for sphinx-build that turns warnings + into errors. + + +Release 0.5.2 (Mar 24, 2009) +============================ + +* Properly escape ``|`` in LaTeX output. + +* #71: If a decoding error occurs in source files, print a + warning and replace the characters by "?". + +* Fix a problem in the HTML search if the index takes too long + to load. + +* Don't output system messages while resolving, because they + would stay in the doctrees even if keep_warnings is false. + +* #82: Determine the correct path for dependencies noted by + docutils. This fixes behavior where a source with dependent + files was always reported as changed. + +* Recognize toctree directives that are not on section toplevel, + but within block items, such as tables. + +* Use a new RFC base URL, since rfc.org seems down. + +* Fix a crash in the todolist directive when no todo items are + defined. + +* Don't call LaTeX or dvipng over and over again if it was not + found once, and use text-only latex as a substitute in that case. + +* Fix problems with footnotes in the LaTeX output. + +* Prevent double hyphens becoming en-dashes in literal code in + the LaTeX output. + +* Open literalinclude files in universal newline mode to allow + arbitrary newline conventions. + +* Actually make the ``-Q`` option work. + +* #86: Fix explicit document titles in toctrees. + +* #81: Write environment and search index in a manner that is safe + from exceptions that occur during dumping. + +* #80: Fix UnicodeErrors when a locale is set with setlocale(). + + +Release 0.5.1 (Dec 15, 2008) +============================ + +* #67: Output warnings about failed doctests in the doctest extension + even when running in quiet mode. + +* #72: In pngmath, make it possible to give a full path to LaTeX and + dvipng on Windows. For that to work, the ``pngmath_latex`` and + ``pngmath_dvipng`` options are no longer split into command and + additional arguments; use ``pngmath_latex_args`` and + ``pngmath_dvipng_args`` to give additional arguments. + +* Don't crash on failing doctests with non-ASCII characters. + +* Don't crash on writing status messages and warnings containing + unencodable characters. + +* Warn if a doctest extension block doesn't contain any code. + +* Fix the handling of ``:param:`` and ``:type:`` doc fields when + they contain markup (especially cross-referencing roles). + +* #65: Fix storage of depth information for PNGs generated by the + pngmath extension. + +* Fix autodoc crash when automethod is used outside a class context. + +* #68: Fix LaTeX writer output for images with specified height. + +* #60: Fix wrong generated image path when including images in sources + in subdirectories. + +* Fix the JavaScript search when html_copy_source is off. + +* Fix an indentation problem in autodoc when documenting classes + with the option ``autoclass_content = "both"`` set. + +* Don't crash on empty index entries, only emit a warning. + +* Fix a typo in the search JavaScript code, leading to unusable + search function in some setups. + + +Release 0.5 (Nov 23, 2008) -- Birthday release! +=============================================== + +New features added +------------------ + +* Markup features: + + - Citations are now global: all citation defined in any file can be + referenced from any file. Citations are collected in a bibliography + for LaTeX output. + + - Footnotes are now properly handled in the LaTeX builder: they appear + at the location of the footnote reference in text, not at the end of + a section. Thanks to Andrew McNamara for the initial patch. + + - "System Message" warnings are now automatically removed from the + built documentation, and only written to stderr. If you want the + old behavior, set the new config value ``keep_warnings`` to True. + + - Glossary entries are now automatically added to the index. + + - Figures with captions can now be referred to like section titles, + using the ``:ref:`` role without an explicit link text. + + - Added ``cmember`` role for consistency. + + - Lists enumerated by letters or roman numerals are now handled like in + standard reST. + + - The ``seealso`` directive can now also be given arguments, as a short + form. + + - You can now document several programs and their options with the + new ``program`` directive. + +* HTML output and templates: + + - Incompatible change: The "root" relation link (top left in the + relbar) now points to the ``master_doc`` by default, no longer to a + document called "index". The old behavior, while useful in some + situations, was somewhat unexpected. Override the "rootrellink" + block in the template to customize where it refers to. + + - The JavaScript search now searches for objects before searching in + the full text. + + - TOC tree entries now have CSS classes that make it possible to + style them depending on their depth. + + - Highlighted code blocks now have CSS classes that make it possible + to style them depending on their language. + + - HTML ```` tags via the docutils :dudir:`meta` directive are now + supported. + + - ``SerializingHTMLBuilder`` was added as new abstract builder that + can be subclassed to serialize build HTML in a specific format. The + ``PickleHTMLBuilder`` is a concrete subclass of it that uses pickle + as serialization implementation. + + - ``JSONHTMLBuilder`` was added as another ``SerializingHTMLBuilder`` + subclass that dumps the generated HTML into JSON files for further + processing. + + - The ``rellinks`` block in the layout template is now called + ``linktags`` to avoid confusion with the relbar links. + + - The HTML builders have two additional attributes now that can be + used to disable the anchor-link creation after headlines and + definition links. + + - Only generate a module index if there are some modules in the + documentation. + +* New and changed config values: + + - Added support for internationalization in generated text with the + ``language`` and ``locale_dirs`` config values. Many thanks to + language contributors: + + * Horst Gutmann -- German + * Pavel Kosina -- Czech + * David Larlet -- French + * Michał Kandulski -- Polish + * Yasushi Masuda -- Japanese + * Guillem Borrell -- Spanish + * Luc Saffre and Peter Bertels -- Dutch + * Fred Lin -- Traditional Chinese + * Roger Demetrescu -- Brazilian Portuguese + * Rok Garbas -- Slovenian + + - The new config value ``highlight_language`` set a global default for + highlighting. When ``'python3'`` is selected, console output blocks + are recognized like for ``'python'``. + + - Exposed Pygments' lexer guessing as a highlight "language" ``guess``. + + - The new config value ``latex_elements`` allows to override all LaTeX + snippets that Sphinx puts into the generated .tex file by default. + + - Added ``exclude_dirnames`` config value that can be used to exclude + e.g. CVS directories from source file search. + + - Added ``source_encoding`` config value to select input encoding. + +* Extensions: + + - The new extensions ``sphinx.ext.jsmath`` and ``sphinx.ext.pngmath`` + provide math support for both HTML and LaTeX builders. + + - The new extension ``sphinx.ext.intersphinx`` half-automatically + creates links to Sphinx documentation of Python objects in other + projects. + + - The new extension ``sphinx.ext.todo`` allows the insertion of + "To do" directives whose visibility in the output can be toggled. + It also adds a directive to compile a list of all todo items. + + - sphinx.ext.autodoc has a new event ``autodoc-process-signature`` + that allows tuning function signature introspection. + + - sphinx.ext.autodoc has a new event ``autodoc-skip-member`` that allows + tuning which members are included in the generated content. + + - Respect __all__ when autodocumenting module members. + + - The ``automodule`` directive now supports the ``synopsis``, + ``deprecated`` and ``platform`` options. + +* Extension API: + + - ``Sphinx.add_node()`` now takes optional visitor methods for the + HTML, LaTeX and text translators; this prevents having to manually + patch the classes. + + - Added ``Sphinx.add_javascript()`` that adds scripts to load in the + default HTML template. + + - Added new events: ``source-read``, ``env-updated``, + ``env-purge-doc``, ``missing-reference``, ``build-finished``. + +* Other changes: + + - Added a command-line switch ``-Q``: it will suppress warnings. + + - Added a command-line switch ``-A``: it can be used to supply + additional values into the HTML templates. + + - Added a command-line switch ``-C``: if it is given, no configuration + file ``conf.py`` is required. + + - Added a distutils command ``build_sphinx``: When Sphinx is installed, + you can call ``python setup.py build_sphinx`` for projects that have + Sphinx documentation, which will build the docs and place them in + the standard distutils build directory. + + - In quickstart, if the selected root path already contains a Sphinx + project, complain and abort. + +Bugs fixed +---------- + +* #51: Escape configuration values placed in HTML templates. + +* #44: Fix small problems in HTML help index generation. + +* Fix LaTeX output for line blocks in tables. + +* #38: Fix "illegal unit" error when using pixel image widths/heights. + +* Support table captions in LaTeX output. + +* #39: Work around a bug in Jinja that caused "" to be + emitted in HTML output. + +* Fix a problem with module links not being generated in LaTeX output. + +* Fix the handling of images in different directories. + +* #29: Support option lists in the text writer. Make sure that dashes + introducing long option names are not contracted to en-dashes. + +* Support the "scale" option for images in HTML output. + +* #25: Properly escape quotes in HTML help attribute values. + +* Fix LaTeX build for some description environments with ``:noindex:``. + +* #24: Don't crash on uncommon casing of role names (like ``:Class:``). + +* Only output ANSI colors on color terminals. + +* Update to newest fncychap.sty, to fix problems with non-ASCII + characters at the start of chapter titles. + +* Fix a problem with index generation in LaTeX output, caused by + hyperref not being included last. + +* Don't disregard return annotations for functions without any parameters. + +* Don't throw away labels for code blocks. + + +Release 0.4.3 (Oct 8, 2008) +=========================== + +* Fix a bug in autodoc with directly given autodoc members. + +* Fix a bug in autodoc that would import a module twice, once as + "module", once as "module.". + +* Fix a bug in the HTML writer that created duplicate ``id`` + attributes for section titles with docutils 0.5. + +* Properly call ``super()`` in overridden blocks in templates. + +* Add a fix when using XeTeX. + +* Unify handling of LaTeX escaping. + +* Rebuild everything when the ``extensions`` config value changes. + +* Don't try to remove a nonexisting static directory. + +* Fix an indentation problem in production lists. + +* Fix encoding handling for literal include files: ``literalinclude`` + now has an ``encoding`` option that defaults to UTF-8. + +* Fix the handling of non-ASCII characters entered in quickstart. + +* Fix a crash with nonexisting image URIs. + + +Release 0.4.2 (Jul 29, 2008) +============================ + +* Fix rendering of the ``samp`` role in HTML. + +* Fix a bug with LaTeX links to headings leading to a wrong page. + +* Reread documents with globbed toctrees when source files are + added or removed. + +* Add a missing parameter to PickleHTMLBuilder.handle_page(). + +* Put inheritance info always on its own line. + +* Don't automatically enclose code with whitespace in it in quotes; + only do this for the ``samp`` role. + +* autodoc now emits a more precise error message when a module + can't be imported or an attribute can't be found. + +* The JavaScript search now uses the correct file name suffix when + referring to found items. + +* The automodule directive now accepts the ``inherited-members`` + and ``show-inheritance`` options again. + +* You can now rebuild the docs normally after relocating the source + and/or doctree directory. + + +Release 0.4.1 (Jul 5, 2008) +=========================== + +* Added sub-/superscript node handling to TextBuilder. + +* Label names in references are now case-insensitive, since reST + label names are always lowercased. + +* Fix linkcheck builder crash for malformed URLs. + +* Add compatibility for admonitions and docutils 0.5. + +* Remove the silly restriction on "rubric" in the LaTeX writer: you + can now write arbitrary "rubric" directives, and only those with + a title of "Footnotes" will be ignored. + +* Copy the HTML logo to the output ``_static`` directory. + +* Fix LaTeX code for modules with underscores in names and platforms. + +* Fix a crash with nonlocal image URIs. + +* Allow the usage of :noindex: in ``automodule`` directives, as + documented. + +* Fix the ``delete()`` docstring processor function in autodoc. + +* Fix warning message for nonexisting images. + +* Fix JavaScript search in Internet Explorer. + + +Release 0.4 (Jun 23, 2008) +========================== + +New features added +------------------ + +* ``tocdepth`` can be given as a file-wide metadata entry, and + specifies the maximum depth of a TOC of this file. + +* The new config value ``default_role`` can be used to select the + default role for all documents. + +* Sphinx now interprets field lists with fields like ``:param foo:`` + in description units. + +* The new ``staticmethod`` directive can be used to mark methods as + static methods. + +* HTML output: + + - The "previous" and "next" links have a more logical structure, so + that by following "next" links you can traverse the entire TOC + tree. + + - The new event ``html-page-context`` can be used to include custom + values into the context used when rendering an HTML template. + + - Document metadata is now in the default template context, under + the name ``metadata``. + + - The new config value ``html_favicon`` can be used to set a favicon + for the HTML output. Thanks to Sebastian Wiesner. + + - The new config value ``html_use_index`` can be used to switch index + generation in HTML documents off. + + - The new config value ``html_split_index`` can be used to create + separate index pages for each letter, to be used when the complete + index is too large for one page. + + - The new config value ``html_short_title`` can be used to set a + shorter title for the documentation which is then used in the + navigation bar. + + - The new config value ``html_show_sphinx`` can be used to control + whether a link to Sphinx is added to the HTML footer. + + - The new config value ``html_file_suffix`` can be used to set the + HTML file suffix to e.g. ``.xhtml``. + + - The directories in the ``html_static_path`` can now contain + subdirectories. + + - The module index now isn't collapsed if the number of submodules + is larger than the number of toplevel modules. + +* The image directive now supports specifying the extension as ``.*``, + which makes the builder select the one that matches best. Thanks to + Sebastian Wiesner. + +* The new config value ``exclude_trees`` can be used to exclude whole + subtrees from the search for source files. + +* Defaults for configuration values can now be callables, which allows + dynamic defaults. + +* The new TextBuilder creates plain-text output. + +* Python 3-style signatures, giving a return annotation via ``->``, + are now supported. + +* Extensions: + + - The autodoc extension now offers a much more flexible way to + manipulate docstrings before including them into the output, via + the new ``autodoc-process-docstring`` event. + + - The ``autodoc`` extension accepts signatures for functions, methods + and classes now that override the signature got via introspection + from Python code. + + - The ``autodoc`` extension now offers a ``show-inheritance`` option + for autoclass that inserts a list of bases after the signature. + + - The autodoc directives now support the ``noindex`` flag option. + + +Bugs fixed +---------- + +* Correctly report the source location for docstrings included with + autodoc. + +* Fix the LaTeX output of description units with multiple signatures. + +* Handle the figure directive in LaTeX output. + +* Handle raw admonitions in LaTeX output. + +* Fix determination of the title in HTML help output. + +* Handle project names containing spaces. + +* Don't write SSI-like comments in HTML output. + +* Rename the "sidebar" class to "sphinxsidebar" in order to stay different + from reST sidebars. + +* Use a binary TOC in HTML help generation to fix issues links without + explicit anchors. + +* Fix behavior of references to functions/methods with an explicit title. + +* Support citation, subscript and superscript nodes in LaTeX writer. + +* Provide the standard "class" directive as "cssclass"; else it is + shadowed by the Sphinx-defined directive. + +* Fix the handling of explicit module names given to autoclass directives. + They now show up with the correct module name in the generated docs. + +* Enable autodoc to process Unicode docstrings. + +* The LaTeX writer now translates line blocks with ``\raggedright``, + which plays nicer with tables. + +* Fix bug with directories in the HTML builder static path. + + +Release 0.3 (May 6, 2008) +========================= + +New features added +------------------ + +* The ``toctree`` directive now supports a ``glob`` option that allows + glob-style entries in the content. + +* If the ``pygments_style`` config value contains a dot it's treated as the + import path of a custom Pygments style class. + +* A new config value, ``exclude_dirs``, can be used to exclude whole + directories from the search for source files. + +* The configuration directory (containing ``conf.py``) can now be set + independently from the source directory. For that, a new command-line + option ``-c`` has been added. + +* A new directive ``tabularcolumns`` can be used to give a tabular column + specification for LaTeX output. Tables now use the ``tabulary`` package. + Literal blocks can now be placed in tables, with several caveats. + +* A new config value, ``latex_use_parts``, can be used to enable parts in LaTeX + documents. + +* Autodoc now skips inherited members for classes, unless you give the + new ``inherited-members`` option. + +* A new config value, ``autoclass_content``, selects if the docstring of the + class' ``__init__`` method is added to the directive's body. + +* Support for C++ class names (in the style ``Class::Function``) in C function + descriptions. + +* Support for a ``toctree_only`` item in items for the ``latex_documents`` + config value. This only includes the documents referenced by TOC trees in the + output, not the rest of the file containing the directive. + +Bugs fixed +---------- + +* sphinx.htmlwriter: Correctly write the TOC file for any structure of the + master document. Also encode non-ASCII characters as entities in TOC + and index file. Remove two remaining instances of hard-coded + "documentation". + +* sphinx.ext.autodoc: descriptors are detected properly now. + +* sphinx.latexwriter: implement all reST admonitions, not just ``note`` + and ``warning``. + +* Lots of little fixes to the LaTeX output and style. + +* Fix OpenSearch template and make template URL absolute. The + ``html_use_opensearch`` config value now must give the base URL. + +* Some unused files are now stripped from the HTML help file build. + + +Release 0.2 (Apr 27, 2008) +========================== + +Incompatible changes +-------------------- + +* Jinja, the template engine used for the default HTML templates, is now + no longer shipped with Sphinx. If it is not installed automatically for + you (it is now listed as a dependency in ``setup.py``), install it manually + from PyPI. This will also be needed if you're using Sphinx from a SVN + checkout; in that case please also remove the ``sphinx/jinja`` directory + that may be left over from old revisions. + +* The clumsy handling of the ``index.html`` template was removed. The config + value ``html_index`` is gone, and ``html_additional_pages`` should be used + instead. If you need it, the old ``index.html`` template is still there, + called ``defindex.html``, and you can port your html_index template, using + Jinja inheritance, by changing your template:: + + {% extends "defindex.html" %} + {% block tables %} + ... old html_index template content ... + {% endblock %} + + and putting ``'index': name of your template`` in ``html_additional_pages``. + +* In the layout template, redundant ``block``\s were removed; you should use + Jinja's standard ``{{ super() }}`` mechanism instead, as explained in the + (newly written) templating docs. + +New features added +------------------ + +* Extension API (Application object): + + - Support a new method, ``add_crossref_type``. It works like + ``add_description_unit`` but the directive will only create a target + and no output. + - Support a new method, ``add_transform``. It takes a standard docutils + ``Transform`` subclass which is then applied by Sphinx' reader on + parsing reST document trees. + - Add support for other template engines than Jinja, by adding an + abstraction called a "template bridge". This class handles rendering + of templates and can be changed using the new configuration value + "template_bridge". + - The config file itself can be an extension (if it provides a ``setup()`` + function). + +* Markup: + + - New directive, ``currentmodule``. It can be used to indicate the module + name of the following documented things without creating index entries. + - Allow giving a different title to documents in the toctree. + - Allow giving multiple options in a ``cmdoption`` directive. + - Fix display of class members without explicit class name given. + +* Templates (HTML output): + + - ``index.html`` renamed to ``defindex.html``, see above. + - There's a new config value, ``html_title``, that controls the overall + "title" of the set of Sphinx docs. It is used instead everywhere instead of + "Projectname vX.Y documentation" now. + - All references to "documentation" in the templates have been removed, so + that it is now easier to use Sphinx for non-documentation documents with + the default templates. + - Templates now have an XHTML doctype, to be consistent with docutils' + HTML output. + - You can now create an OpenSearch description file with the + ``html_use_opensearch`` config value. + - You can now quickly include a logo in the sidebar, using the ``html_logo`` + config value. + - There are new blocks in the sidebar, so that you can easily insert content + into the sidebar. + +* LaTeX output: + + - The ``sphinx.sty`` package was cleaned of unused stuff. + - You can include a logo in the title page with the ``latex_logo`` config + value. + - You can define the link colors and a border and background color for + verbatim environments. + +Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and Sebastian +Wiesner for suggestions. + +Bugs fixed +---------- + +* sphinx.ext.autodoc: Don't check ``__module__`` for explicitly given + members. Remove "self" in class constructor argument list. + +* sphinx.htmlwriter: Don't use os.path for joining image HREFs. + +* sphinx.htmlwriter: Don't use SmartyPants for HTML attribute values. + +* sphinx.latexwriter: Implement option lists. Also, some other changes + were made to ``sphinx.sty`` in order to enhance compatibility and + remove old unused stuff. Thanks to Gael Varoquaux for that! + +* sphinx.roles: Fix referencing glossary terms with explicit targets. + +* sphinx.environment: Don't swallow TOC entries when resolving subtrees. + +* sphinx.quickstart: Create a sensible default latex_documents setting. + +* sphinx.builder, sphinx.environment: Gracefully handle some user error + cases. + +* sphinx.util: Follow symbolic links when searching for documents. + + +Release 0.1.61950 (Mar 26, 2008) +================================ + +* sphinx.quickstart: Fix format string for Makefile. + + +Release 0.1.61945 (Mar 26, 2008) +================================ + +* sphinx.htmlwriter, sphinx.latexwriter: Support the ``.. image::`` + directive by copying image files to the output directory. + +* sphinx.builder: Consistently name "special" HTML output directories + with a leading underscore; this means ``_sources`` and ``_static``. + +* sphinx.environment: Take dependent files into account when collecting + the set of outdated sources. + +* sphinx.directives: Record files included with ``.. literalinclude::`` + as dependencies. + +* sphinx.ext.autodoc: Record files from which docstrings are included + as dependencies. + +* sphinx.builder: Rebuild all HTML files in case of a template change. + +* sphinx.builder: Handle unavailability of TOC relations (previous/ + next chapter) more gracefully in the HTML builder. + +* sphinx.latexwriter: Include fncychap.sty which doesn't seem to be + very common in TeX distributions. Add a ``clean`` target in the + latex Makefile. Really pass the correct paper and size options + to the LaTeX document class. + +* setup: On Python 2.4, don't egg-depend on docutils if a docutils is + already installed -- else it will be overwritten. + + +Release 0.1.61843 (Mar 24, 2008) +================================ + +* sphinx.quickstart: Really don't create a makefile if the user + doesn't want one. + +* setup: Don't install scripts twice, via setuptools entry points + and distutils scripts. Only install via entry points. + +* sphinx.builder: Don't recognize the HTML builder's copied source + files (under ``_sources``) as input files if the source suffix is + ``.txt``. + +* sphinx.highlighting: Generate correct markup for LaTeX Verbatim + environment escapes even if Pygments is not installed. + +* sphinx.builder: The WebHTMLBuilder is now called PickleHTMLBuilder. + +* sphinx.htmlwriter: Make parsed-literal blocks work as expected, + not highlighting them via Pygments. + +* sphinx.environment: Don't error out on reading an empty source file. + + +Release 0.1.61798 (Mar 23, 2008) +================================ + +* sphinx: Work with docutils SVN snapshots as well as 0.4. + +* sphinx.ext.doctest: Make the group in which doctest blocks are + placed selectable, and default to ``'default'``. + +* sphinx.ext.doctest: Replace ```` in doctest blocks by + real blank lines for presentation output, and remove doctest + options given inline. + +* sphinx.environment: Move doctest_blocks out of block_quotes to + support indented doctest blocks. + +* sphinx.ext.autodoc: Render ``.. automodule::`` docstrings in a + section node, so that module docstrings can contain proper + sectioning. + +* sphinx.ext.autodoc: Use the module's encoding for decoding + docstrings, rather than requiring ASCII. + + +Release 0.1.61611 (Mar 21, 2008) +================================ -The changelog for versions before 1.0 can be found in the file ``CHANGES.old`` -in the source distribution or `at GitHub -`__. +* First public release. diff --git a/CHANGES.old b/CHANGES.old deleted file mode 100644 index b94a99e4bc1..00000000000 --- a/CHANGES.old +++ /dev/null @@ -1,1249 +0,0 @@ -For the changelog from version 1.0, look at the file CHANGES. - -Release 0.6.7 (Jun 05, 2010) -============================ - -* #440: Remove usage of a Python >= 2.5 API in the ``literalinclude`` - directive. - -* Fix a bug that prevented some references being generated in the - LaTeX builder. - -* #428: Add some missing CSS styles for standard docutils classes. - -* #432: Fix UnicodeErrors while building LaTeX in translated locale. - - -Release 0.6.6 (May 25, 2010) -============================ - -* Handle raw nodes in the ``text`` writer. - -* Fix a problem the Qt help project generated by the ``qthelp`` - builder that would lead to no content being displayed in the Qt - Assistant. - -* #393: Fix the usage of Unicode characters in mathematic formulas - when using the ``pngmath`` extension. - -* #404: Make ``\and`` work properly in the author field of the - ``latex_documents`` setting. - -* #409: Make the ``highlight_language`` config value work properly - in the LaTeX builder. - -* #418: Allow relocation of the translation JavaScript files to - the system directory on Unix systems. - -* #414: Fix handling of Windows newlines in files included with - the ``literalinclude`` directive. - -* #377: Fix crash in linkcheck builder. - -* #387: Fix the display of search results in ``dirhtml`` output. - -* #376: In autodoc, fix display of parameter defaults containing - backslashes. - -* #370: Fix handling of complex list item labels in LaTeX output. - -* #374: Make the ``doctest_path`` config value of the doctest - extension actually work. - -* Fix the handling of multiple toctrees when creating the global - TOC for the ``toctree()`` template function. - -* Fix the handling of hidden toctrees when creating the global TOC - for the ``toctree()`` template function. - -* Fix the handling of nested lists in the text writer. - -* #362: In autodoc, check for the existence of ``__self__`` on - function objects before accessing it. - -* #353: Strip leading and trailing whitespace when extracting - search words in the search function. - - -Release 0.6.5 (Mar 01, 2010) -============================ - -* In autodoc, fix the omission of some module members explicitly - documented using documentation comments. - -* #345: Fix cropping of sidebar scroll bar with ``stickysidebar`` - option of the default theme. - -* #341: Always generate UNIX newlines in the quickstart Makefile. - -* #338: Fix running with ``-C`` under Windows. - -* In autodoc, allow customizing the signature of an object where - the built-in mechanism fails. - -* #331: Fix output for enumerated lists with start values in LaTeX. - -* Make the ``start-after`` and ``end-before`` options to the - ``literalinclude`` directive work correctly if not used together. - -* #321: Fix link generation in the LaTeX builder. - - -Release 0.6.4 (Jan 12, 2010) -============================ - -* Improve the handling of non-Unicode strings in the configuration. - -* #316: Catch OSErrors occurring when calling graphviz with - arguments it doesn't understand. - -* Restore compatibility with Pygments >= 1.2. - -* #295: Fix escaping of hyperref targets in LaTeX output. - -* #302: Fix links generated by the ``:doc:`` role for LaTeX output. - -* #286: collect todo nodes after the whole document has been read; - this allows placing substitution references in todo items. - -* #294: do not ignore an explicit ``today`` config value in a - LaTeX build. - -* The ``alt`` text of inheritance diagrams is now much cleaner. - -* Ignore images in section titles when generating link captions. - -* #310: support exception messages in the ``testoutput`` blocks of - the ``doctest`` extension. - -* #293: line blocks are styled properly in HTML output. - -* #285: make the ``locale_dirs`` config value work again. - -* #303: ``html_context`` values given on the command line via ``-A`` - should not override other values given in conf.py. - -* Fix a bug preventing incremental rebuilds for the ``dirhtml`` - builder. - -* #299: Fix the mangling of quotes in some literal blocks. - -* #292: Fix path to the search index for the ``dirhtml`` builder. - -* Fix a Jython compatibility issue: make the dependence on the - ``parser`` module optional. - -* #238: In autodoc, catch all errors that occur on module import, - not just ``ImportError``. - -* Fix the handling of non-data, but non-method descriptors in autodoc. - -* When copying file times, ignore OSErrors raised by ``os.utime()``. - - -Release 0.6.3 (Sep 03, 2009) -============================ - -* Properly add C module filenames as dependencies in autodoc. - -* #253: Ignore graphviz directives without content instead of - raising an unhandled exception. - -* #241: Fix a crash building LaTeX output for documents that contain - a todolist directive. - -* #252: Make it easier to change the build dir in the Makefiles - generated by quickstart. - -* #220: Fix CSS so that displaymath really is centered. - -* #222: Allow the "Footnotes" header to be translated. - -* #225: Don't add whitespace in generated HTML after inline tags. - -* #227: Make ``literalinclude`` work when the document's path - name contains non-ASCII characters. - -* #229: Fix autodoc failures with members that raise errors - on ``getattr()``. - -* #205: When copying files, don't copy full stat info, only - modification times. - -* #232: Support non-ASCII metadata in Qt help builder. - -* Properly format bullet lists nested in definition lists for LaTeX. - -* Section titles are now allowed inside ``only`` directives. - -* #201: Make ``centered`` directive work in LaTeX output. - -* #206: Refuse to overwrite an existing master document in - sphinx-quickstart. - -* #208: Use MS-sanctioned locale settings, determined by the - ``language`` config option, in the HTML help builder. - -* #210: Fix nesting of HTML tags for displayed math from pngmath - extension. - -* #213: Fix centering of images in LaTeX output. - -* #211: Fix compatibility with docutils 0.5. - - -Release 0.6.2 (Jun 16, 2009) -============================ - -* #130: Fix obscure IndexError in doctest extension. - -* #167: Make glossary sorting case-independent. - -* #196: Add a warning if an extension module doesn't have a - ``setup()`` function. - -* #158: Allow '..' in template names, and absolute template paths; - Jinja 2 by default disables both. - -* When highlighting Python code, ignore extra indentation before - trying to parse it as Python. - -* #191: Don't escape the tilde in URIs in LaTeX. - -* Don't consider contents of source comments for the search index. - -* Set the default encoding to ``utf-8-sig`` to handle files with a - UTF-8 BOM correctly. - -* #178: apply ``add_function_parentheses`` config value to C - functions as promised. - -* #173: Respect the docutils ``title`` directive. - -* #172: The ``obj`` role now links to modules as promised. - -* #19: Tables now can have a "longtable" class, in order to get - correctly broken into pages in LaTeX output. - -* Look for Sphinx message catalogs in the system default path before - trying ``sphinx/locale``. - -* Fix the search for methods via "classname.methodname". - -* #155: Fix Python 2.4 compatibility: exceptions are old-style - classes there. - -* #150: Fix display of the "sphinxdoc" theme on Internet Explorer - versions 6 and 7. - -* #146: Don't fail to generate LaTeX when the user has an active - ``.docutils`` configuration. - -* #29: Don't generate visible "-{-}" in option lists in LaTeX. - -* Fix cross-reference roles when put into substitutions. - -* Don't put image "alt" text into table-of-contents entries. - -* In the LaTeX writer, do not raise an exception on too many section - levels, just use the "subparagraph" level for all of them. - -* #145: Fix autodoc problem with automatic members that refuse to be - getattr()'d from their parent. - -* If specific filenames to build are given on the command line, - check that they are within the source directory. - -* Fix autodoc crash for objects without a ``__name__``. - -* Fix intersphinx for installations without urllib2.HTTPSHandler. - -* #134: Fix pending_xref leftover nodes when using the todolist - directive from the todo extension. - - -Release 0.6.1 (Mar 26, 2009) -============================ - -* #135: Fix problems with LaTeX output and the graphviz extension. - -* #132: Include the autosummary "module" template in the distribution. - - -Release 0.6 (Mar 24, 2009) -========================== - -New features added ------------------- - -* Incompatible changes: - - - Templating now requires the Jinja2 library, which is an enhanced - version of the old Jinja1 engine. Since the syntax and semantic - is largely the same, very few fixes should be necessary in - custom templates. - - - The "document" div tag has been moved out of the ``layout.html`` - template's "document" block, because the closing tag was already - outside. If you overwrite this block, you need to remove your - "document" div tag as well. - - - The ``autodoc_skip_member`` event now also gets to decide - whether to skip members whose name starts with underscores. - Previously, these members were always automatically skipped. - Therefore, if you handle this event, add something like this - to your event handler to restore the old behavior:: - - if name.startswith('_'): - return True - -* Theming support, see the new section in the documentation. - -* Markup: - - - Due to popular demand, added a ``:doc:`` role which directly - links to another document without the need of creating a - label to which a ``:ref:`` could link to. - - - #4: Added a ``:download:`` role that marks a non-document file - for inclusion into the HTML output and links to it. - - - Added an ``only`` directive that can selectively include text - based on enabled "tags". Tags can be given on the command - line. Also, the current builder output format (e.g. "html" or - "latex") is always a defined tag. - - - #10: Added HTML section numbers, enabled by giving a - ``:numbered:`` flag to the ``toctree`` directive. - - - #114: Added an ``abbr`` role to markup abbreviations and - acronyms. - - - The ``literalinclude`` directive now supports several more - options, to include only parts of a file. - - - The ``toctree`` directive now supports a ``:hidden:`` flag, - which will prevent links from being generated in place of - the directive -- this allows you to define your document - structure, but place the links yourself. - - - #123: The ``glossary`` directive now supports a ``:sorted:`` - flag that sorts glossary entries alphabetically. - - - Paths to images, literal include files and download files - can now be absolute (like ``/images/foo.png``). They are - treated as relative to the top source directory. - - - #52: There is now a ``hlist`` directive, creating a compact - list by placing distributing items into multiple columns. - - - #77: If a description environment with info field list only - contains one ``:param:`` entry, no bullet list is generated. - - - #6: Don't generate redundant ``
      `` for top-level TOC tree - items, which leads to a visual separation of TOC entries. - - - #23: Added a ``classmethod`` directive along with ``method`` - and ``staticmethod``. - - - Scaled images now get a link to the unscaled version. - - - SVG images are now supported in HTML (via ```` and - ```` tags). - - - Added a ``toctree`` callable to the templates, and the ability - to include external links in toctrees. The 'collapse' keyword - argument indicates whether or not to only display subitems of - the current page. (Defaults to True.) - -* Configuration: - - - The new config value ``rst_epilog`` can contain reST that is - appended to each source file that is read. This is the right - place for global substitutions. - - - The new ``html_add_permalinks`` config value can be used to - switch off the generated "paragraph sign" permalinks for each - heading and definition environment. - - - The new ``html_show_sourcelink`` config value can be used to - switch off the links to the reST sources in the sidebar. - - - The default value for ``htmlhelp_basename`` is now the project - title, cleaned up as a filename. - - - The new ``modindex_common_prefix`` config value can be used to - ignore certain package names for module index sorting. - - - The new ``trim_footnote_reference_space`` config value mirrors - the docutils config value of the same name and removes the - space before a footnote reference that is necessary for reST - to recognize the reference. - - - The new ``latex_additional_files`` config value can be used to - copy files (that Sphinx doesn't copy automatically, e.g. if they - are referenced in custom LaTeX added in ``latex_elements``) to - the build directory. - -* Builders: - - - The HTML builder now stores a small file named ``.buildinfo`` in - its output directory. It stores a hash of config values that - can be used to determine if a full rebuild needs to be done (e.g. - after changing ``html_theme``). - - - New builder for Qt help collections, by Antonio Valentino. - - - The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates - a separate directory for every page, and places the page there - in a file called ``index.html``. Therefore, page URLs and links - don't need to contain ``.html``. - - - The new ``html_link_suffix`` config value can be used to select - the suffix of generated links between HTML files. - - - #96: The LaTeX builder now supports figures wrapped by text, when - using the ``figwidth`` option and right/left alignment. - -* New translations: - - - Italian by Sandro Dentella. - - Ukrainian by Petro Sasnyk. - - Finnish by Jukka Inkeri. - - Russian by Alexander Smishlajev. - -* Extensions and API: - - - New ``graphviz`` extension to embed graphviz graphs. - - - New ``inheritance_diagram`` extension to embed... inheritance - diagrams! - - - New ``autosummary`` extension that generates summaries of - modules and automatic documentation of modules. - - - Autodoc now has a reusable Python API, which can be used to - create custom types of objects to auto-document (e.g. Zope - interfaces). See also ``Sphinx.add_autodocumenter()``. - - - Autodoc now handles documented attributes. - - - Autodoc now handles inner classes and their methods. - - - Autodoc can document classes as functions now if explicitly - marked with `autofunction`. - - - Autodoc can now exclude single members from documentation - via the ``exclude-members`` option. - - - Autodoc can now order members either alphabetically (like - previously) or by member type; configurable either with the - config value ``autodoc_member_order`` or a ``member-order`` - option per directive. - - - The function ``Sphinx.add_directive()`` now also supports - docutils 0.5-style directive classes. If they inherit from - ``sphinx.util.compat.Directive``, they also work with - docutils 0.4. - - - There is now a ``Sphinx.add_lexer()`` method to be able to use - custom Pygments lexers easily. - - - There is now ``Sphinx.add_generic_role()`` to mirror the - docutils' own function. - -* Other changes: - - - Config overrides for single dict keys can now be given on the - command line. - - - There is now a ``doctest_global_setup`` config value that can - be used to give setup code for all doctests in the documentation. - - - Source links in HTML are now generated with ``rel="nofollow"``. - - - Quickstart can now generate a Windows ``make.bat`` file. - - - #62: There is now a ``-w`` option for sphinx-build that writes - warnings to a file, in addition to stderr. - - - There is now a ``-W`` option for sphinx-build that turns warnings - into errors. - - -Release 0.5.2 (Mar 24, 2009) -============================ - -* Properly escape ``|`` in LaTeX output. - -* #71: If a decoding error occurs in source files, print a - warning and replace the characters by "?". - -* Fix a problem in the HTML search if the index takes too long - to load. - -* Don't output system messages while resolving, because they - would stay in the doctrees even if keep_warnings is false. - -* #82: Determine the correct path for dependencies noted by - docutils. This fixes behavior where a source with dependent - files was always reported as changed. - -* Recognize toctree directives that are not on section toplevel, - but within block items, such as tables. - -* Use a new RFC base URL, since rfc.org seems down. - -* Fix a crash in the todolist directive when no todo items are - defined. - -* Don't call LaTeX or dvipng over and over again if it was not - found once, and use text-only latex as a substitute in that case. - -* Fix problems with footnotes in the LaTeX output. - -* Prevent double hyphens becoming en-dashes in literal code in - the LaTeX output. - -* Open literalinclude files in universal newline mode to allow - arbitrary newline conventions. - -* Actually make the ``-Q`` option work. - -* #86: Fix explicit document titles in toctrees. - -* #81: Write environment and search index in a manner that is safe - from exceptions that occur during dumping. - -* #80: Fix UnicodeErrors when a locale is set with setlocale(). - - -Release 0.5.1 (Dec 15, 2008) -============================ - -* #67: Output warnings about failed doctests in the doctest extension - even when running in quiet mode. - -* #72: In pngmath, make it possible to give a full path to LaTeX and - dvipng on Windows. For that to work, the ``pngmath_latex`` and - ``pngmath_dvipng`` options are no longer split into command and - additional arguments; use ``pngmath_latex_args`` and - ``pngmath_dvipng_args`` to give additional arguments. - -* Don't crash on failing doctests with non-ASCII characters. - -* Don't crash on writing status messages and warnings containing - unencodable characters. - -* Warn if a doctest extension block doesn't contain any code. - -* Fix the handling of ``:param:`` and ``:type:`` doc fields when - they contain markup (especially cross-referencing roles). - -* #65: Fix storage of depth information for PNGs generated by the - pngmath extension. - -* Fix autodoc crash when automethod is used outside a class context. - -* #68: Fix LaTeX writer output for images with specified height. - -* #60: Fix wrong generated image path when including images in sources - in subdirectories. - -* Fix the JavaScript search when html_copy_source is off. - -* Fix an indentation problem in autodoc when documenting classes - with the option ``autoclass_content = "both"`` set. - -* Don't crash on empty index entries, only emit a warning. - -* Fix a typo in the search JavaScript code, leading to unusable - search function in some setups. - - -Release 0.5 (Nov 23, 2008) -- Birthday release! -=============================================== - -New features added ------------------- - -* Markup features: - - - Citations are now global: all citation defined in any file can be - referenced from any file. Citations are collected in a bibliography - for LaTeX output. - - - Footnotes are now properly handled in the LaTeX builder: they appear - at the location of the footnote reference in text, not at the end of - a section. Thanks to Andrew McNamara for the initial patch. - - - "System Message" warnings are now automatically removed from the - built documentation, and only written to stderr. If you want the - old behavior, set the new config value ``keep_warnings`` to True. - - - Glossary entries are now automatically added to the index. - - - Figures with captions can now be referred to like section titles, - using the ``:ref:`` role without an explicit link text. - - - Added ``cmember`` role for consistency. - - - Lists enumerated by letters or roman numerals are now handled like in - standard reST. - - - The ``seealso`` directive can now also be given arguments, as a short - form. - - - You can now document several programs and their options with the - new ``program`` directive. - -* HTML output and templates: - - - Incompatible change: The "root" relation link (top left in the - relbar) now points to the ``master_doc`` by default, no longer to a - document called "index". The old behavior, while useful in some - situations, was somewhat unexpected. Override the "rootrellink" - block in the template to customize where it refers to. - - - The JavaScript search now searches for objects before searching in - the full text. - - - TOC tree entries now have CSS classes that make it possible to - style them depending on their depth. - - - Highlighted code blocks now have CSS classes that make it possible - to style them depending on their language. - - - HTML ```` tags via the docutils ``meta`` directive are now - supported. - - - ``SerializingHTMLBuilder`` was added as new abstract builder that - can be subclassed to serialize build HTML in a specific format. The - ``PickleHTMLBuilder`` is a concrete subclass of it that uses pickle - as serialization implementation. - - - ``JSONHTMLBuilder`` was added as another ``SerializingHTMLBuilder`` - subclass that dumps the generated HTML into JSON files for further - processing. - - - The ``rellinks`` block in the layout template is now called - ``linktags`` to avoid confusion with the relbar links. - - - The HTML builders have two additional attributes now that can be - used to disable the anchor-link creation after headlines and - definition links. - - - Only generate a module index if there are some modules in the - documentation. - -* New and changed config values: - - - Added support for internationalization in generated text with the - ``language`` and ``locale_dirs`` config values. Many thanks to - language contributors: - - * Horst Gutmann -- German - * Pavel Kosina -- Czech - * David Larlet -- French - * Michał Kandulski -- Polish - * Yasushi Masuda -- Japanese - * Guillem Borrell -- Spanish - * Luc Saffre and Peter Bertels -- Dutch - * Fred Lin -- Traditional Chinese - * Roger Demetrescu -- Brazilian Portuguese - * Rok Garbas -- Slovenian - - - The new config value ``highlight_language`` set a global default for - highlighting. When ``'python3'`` is selected, console output blocks - are recognized like for ``'python'``. - - - Exposed Pygments' lexer guessing as a highlight "language" ``guess``. - - - The new config value ``latex_elements`` allows to override all LaTeX - snippets that Sphinx puts into the generated .tex file by default. - - - Added ``exclude_dirnames`` config value that can be used to exclude - e.g. CVS directories from source file search. - - - Added ``source_encoding`` config value to select input encoding. - -* Extensions: - - - The new extensions ``sphinx.ext.jsmath`` and ``sphinx.ext.pngmath`` - provide math support for both HTML and LaTeX builders. - - - The new extension ``sphinx.ext.intersphinx`` half-automatically - creates links to Sphinx documentation of Python objects in other - projects. - - - The new extension ``sphinx.ext.todo`` allows the insertion of - "To do" directives whose visibility in the output can be toggled. - It also adds a directive to compile a list of all todo items. - - - sphinx.ext.autodoc has a new event ``autodoc-process-signature`` - that allows tuning function signature introspection. - - - sphinx.ext.autodoc has a new event ``autodoc-skip-member`` that allows - tuning which members are included in the generated content. - - - Respect __all__ when autodocumenting module members. - - - The `automodule` directive now supports the ``synopsis``, - ``deprecated`` and ``platform`` options. - -* Extension API: - - - ``Sphinx.add_node()`` now takes optional visitor methods for the - HTML, LaTeX and text translators; this prevents having to manually - patch the classes. - - - Added ``Sphinx.add_javascript()`` that adds scripts to load in the - default HTML template. - - - Added new events: ``source-read``, ``env-updated``, - ``env-purge-doc``, ``missing-reference``, ``build-finished``. - -* Other changes: - - - Added a command-line switch ``-Q``: it will suppress warnings. - - - Added a command-line switch ``-A``: it can be used to supply - additional values into the HTML templates. - - - Added a command-line switch ``-C``: if it is given, no configuration - file ``conf.py`` is required. - - - Added a distutils command `build_sphinx`: When Sphinx is installed, - you can call ``python setup.py build_sphinx`` for projects that have - Sphinx documentation, which will build the docs and place them in - the standard distutils build directory. - - - In quickstart, if the selected root path already contains a Sphinx - project, complain and abort. - -Bugs fixed ----------- - -* #51: Escape configuration values placed in HTML templates. - -* #44: Fix small problems in HTML help index generation. - -* Fix LaTeX output for line blocks in tables. - -* #38: Fix "illegal unit" error when using pixel image widths/heights. - -* Support table captions in LaTeX output. - -* #39: Work around a bug in Jinja that caused "" to be - emitted in HTML output. - -* Fix a problem with module links not being generated in LaTeX output. - -* Fix the handling of images in different directories. - -* #29: Support option lists in the text writer. Make sure that dashes - introducing long option names are not contracted to en-dashes. - -* Support the "scale" option for images in HTML output. - -* #25: Properly escape quotes in HTML help attribute values. - -* Fix LaTeX build for some description environments with ``:noindex:``. - -* #24: Don't crash on uncommon casing of role names (like ``:Class:``). - -* Only output ANSI colors on color terminals. - -* Update to newest fncychap.sty, to fix problems with non-ASCII - characters at the start of chapter titles. - -* Fix a problem with index generation in LaTeX output, caused by - hyperref not being included last. - -* Don't disregard return annotations for functions without any parameters. - -* Don't throw away labels for code blocks. - - -Release 0.4.3 (Oct 8, 2008) -=========================== - -* Fix a bug in autodoc with directly given autodoc members. - -* Fix a bug in autodoc that would import a module twice, once as - "module", once as "module.". - -* Fix a bug in the HTML writer that created duplicate ``id`` - attributes for section titles with docutils 0.5. - -* Properly call ``super()`` in overridden blocks in templates. - -* Add a fix when using XeTeX. - -* Unify handling of LaTeX escaping. - -* Rebuild everything when the ``extensions`` config value changes. - -* Don't try to remove a nonexisting static directory. - -* Fix an indentation problem in production lists. - -* Fix encoding handling for literal include files: ``literalinclude`` - now has an ``encoding`` option that defaults to UTF-8. - -* Fix the handling of non-ASCII characters entered in quickstart. - -* Fix a crash with nonexisting image URIs. - - -Release 0.4.2 (Jul 29, 2008) -============================ - -* Fix rendering of the ``samp`` role in HTML. - -* Fix a bug with LaTeX links to headings leading to a wrong page. - -* Reread documents with globbed toctrees when source files are - added or removed. - -* Add a missing parameter to PickleHTMLBuilder.handle_page(). - -* Put inheritance info always on its own line. - -* Don't automatically enclose code with whitespace in it in quotes; - only do this for the ``samp`` role. - -* autodoc now emits a more precise error message when a module - can't be imported or an attribute can't be found. - -* The JavaScript search now uses the correct file name suffix when - referring to found items. - -* The automodule directive now accepts the ``inherited-members`` - and ``show-inheritance`` options again. - -* You can now rebuild the docs normally after relocating the source - and/or doctree directory. - - -Release 0.4.1 (Jul 5, 2008) -=========================== - -* Added sub-/superscript node handling to TextBuilder. - -* Label names in references are now case-insensitive, since reST - label names are always lowercased. - -* Fix linkcheck builder crash for malformed URLs. - -* Add compatibility for admonitions and docutils 0.5. - -* Remove the silly restriction on "rubric" in the LaTeX writer: you - can now write arbitrary "rubric" directives, and only those with - a title of "Footnotes" will be ignored. - -* Copy the HTML logo to the output ``_static`` directory. - -* Fix LaTeX code for modules with underscores in names and platforms. - -* Fix a crash with nonlocal image URIs. - -* Allow the usage of :noindex: in ``automodule`` directives, as - documented. - -* Fix the ``delete()`` docstring processor function in autodoc. - -* Fix warning message for nonexisting images. - -* Fix JavaScript search in Internet Explorer. - - -Release 0.4 (Jun 23, 2008) -========================== - -New features added ------------------- - -* ``tocdepth`` can be given as a file-wide metadata entry, and - specifies the maximum depth of a TOC of this file. - -* The new config value `default_role` can be used to select the - default role for all documents. - -* Sphinx now interprets field lists with fields like ``:param foo:`` - in description units. - -* The new `staticmethod` directive can be used to mark methods as - static methods. - -* HTML output: - - - The "previous" and "next" links have a more logical structure, so - that by following "next" links you can traverse the entire TOC - tree. - - - The new event `html-page-context` can be used to include custom - values into the context used when rendering an HTML template. - - - Document metadata is now in the default template context, under - the name `metadata`. - - - The new config value `html_favicon` can be used to set a favicon - for the HTML output. Thanks to Sebastian Wiesner. - - - The new config value `html_use_index` can be used to switch index - generation in HTML documents off. - - - The new config value `html_split_index` can be used to create - separate index pages for each letter, to be used when the complete - index is too large for one page. - - - The new config value `html_short_title` can be used to set a - shorter title for the documentation which is then used in the - navigation bar. - - - The new config value `html_show_sphinx` can be used to control - whether a link to Sphinx is added to the HTML footer. - - - The new config value `html_file_suffix` can be used to set the - HTML file suffix to e.g. ``.xhtml``. - - - The directories in the `html_static_path` can now contain - subdirectories. - - - The module index now isn't collapsed if the number of submodules - is larger than the number of toplevel modules. - -* The image directive now supports specifying the extension as ``.*``, - which makes the builder select the one that matches best. Thanks to - Sebastian Wiesner. - -* The new config value `exclude_trees` can be used to exclude whole - subtrees from the search for source files. - -* Defaults for configuration values can now be callables, which allows - dynamic defaults. - -* The new TextBuilder creates plain-text output. - -* Python 3-style signatures, giving a return annotation via ``->``, - are now supported. - -* Extensions: - - - The autodoc extension now offers a much more flexible way to - manipulate docstrings before including them into the output, via - the new `autodoc-process-docstring` event. - - - The `autodoc` extension accepts signatures for functions, methods - and classes now that override the signature got via introspection - from Python code. - - - The `autodoc` extension now offers a ``show-inheritance`` option - for autoclass that inserts a list of bases after the signature. - - - The autodoc directives now support the ``noindex`` flag option. - - -Bugs fixed ----------- - -* Correctly report the source location for docstrings included with - autodoc. - -* Fix the LaTeX output of description units with multiple signatures. - -* Handle the figure directive in LaTeX output. - -* Handle raw admonitions in LaTeX output. - -* Fix determination of the title in HTML help output. - -* Handle project names containing spaces. - -* Don't write SSI-like comments in HTML output. - -* Rename the "sidebar" class to "sphinxsidebar" in order to stay different - from reST sidebars. - -* Use a binary TOC in HTML help generation to fix issues links without - explicit anchors. - -* Fix behavior of references to functions/methods with an explicit title. - -* Support citation, subscript and superscript nodes in LaTeX writer. - -* Provide the standard "class" directive as "cssclass"; else it is - shadowed by the Sphinx-defined directive. - -* Fix the handling of explicit module names given to autoclass directives. - They now show up with the correct module name in the generated docs. - -* Enable autodoc to process Unicode docstrings. - -* The LaTeX writer now translates line blocks with ``\raggedright``, - which plays nicer with tables. - -* Fix bug with directories in the HTML builder static path. - - -Release 0.3 (May 6, 2008) -========================= - -New features added ------------------- - -* The ``toctree`` directive now supports a ``glob`` option that allows - glob-style entries in the content. - -* If the `pygments_style` config value contains a dot it's treated as the - import path of a custom Pygments style class. - -* A new config value, `exclude_dirs`, can be used to exclude whole - directories from the search for source files. - -* The configuration directory (containing ``conf.py``) can now be set - independently from the source directory. For that, a new command-line - option ``-c`` has been added. - -* A new directive ``tabularcolumns`` can be used to give a tabular column - specification for LaTeX output. Tables now use the ``tabulary`` package. - Literal blocks can now be placed in tables, with several caveats. - -* A new config value, `latex_use_parts`, can be used to enable parts in LaTeX - documents. - -* Autodoc now skips inherited members for classes, unless you give the - new ``inherited-members`` option. - -* A new config value, `autoclass_content`, selects if the docstring of the - class' ``__init__`` method is added to the directive's body. - -* Support for C++ class names (in the style ``Class::Function``) in C function - descriptions. - -* Support for a ``toctree_only`` item in items for the ``latex_documents`` - config value. This only includes the documents referenced by TOC trees in the - output, not the rest of the file containing the directive. - -Bugs fixed ----------- - -* sphinx.htmlwriter: Correctly write the TOC file for any structure of the - master document. Also encode non-ASCII characters as entities in TOC - and index file. Remove two remaining instances of hard-coded - "documentation". - -* sphinx.ext.autodoc: descriptors are detected properly now. - -* sphinx.latexwriter: implement all reST admonitions, not just ``note`` - and ``warning``. - -* Lots of little fixes to the LaTeX output and style. - -* Fix OpenSearch template and make template URL absolute. The - `html_use_opensearch` config value now must give the base URL. - -* Some unused files are now stripped from the HTML help file build. - - -Release 0.2 (Apr 27, 2008) -========================== - -Incompatible changes --------------------- - -* Jinja, the template engine used for the default HTML templates, is now - no longer shipped with Sphinx. If it is not installed automatically for - you (it is now listed as a dependency in ``setup.py``), install it manually - from PyPI. This will also be needed if you're using Sphinx from a SVN - checkout; in that case please also remove the ``sphinx/jinja`` directory - that may be left over from old revisions. - -* The clumsy handling of the ``index.html`` template was removed. The config - value ``html_index`` is gone, and ``html_additional_pages`` should be used - instead. If you need it, the old ``index.html`` template is still there, - called ``defindex.html``, and you can port your html_index template, using - Jinja inheritance, by changing your template:: - - {% extends "defindex.html" %} - {% block tables %} - ... old html_index template content ... - {% endblock %} - - and putting ``'index': name of your template`` in ``html_additional_pages``. - -* In the layout template, redundant ``block``\s were removed; you should use - Jinja's standard ``{{ super() }}`` mechanism instead, as explained in the - (newly written) templating docs. - -New features added ------------------- - -* Extension API (Application object): - - - Support a new method, ``add_crossref_type``. It works like - ``add_description_unit`` but the directive will only create a target - and no output. - - Support a new method, ``add_transform``. It takes a standard docutils - ``Transform`` subclass which is then applied by Sphinx' reader on - parsing reST document trees. - - Add support for other template engines than Jinja, by adding an - abstraction called a "template bridge". This class handles rendering - of templates and can be changed using the new configuration value - "template_bridge". - - The config file itself can be an extension (if it provides a ``setup()`` - function). - -* Markup: - - - New directive, ``currentmodule``. It can be used to indicate the module - name of the following documented things without creating index entries. - - Allow giving a different title to documents in the toctree. - - Allow giving multiple options in a ``cmdoption`` directive. - - Fix display of class members without explicit class name given. - -* Templates (HTML output): - - - ``index.html`` renamed to ``defindex.html``, see above. - - There's a new config value, ``html_title``, that controls the overall - "title" of the set of Sphinx docs. It is used instead everywhere instead of - "Projectname vX.Y documentation" now. - - All references to "documentation" in the templates have been removed, so - that it is now easier to use Sphinx for non-documentation documents with - the default templates. - - Templates now have an XHTML doctype, to be consistent with docutils' - HTML output. - - You can now create an OpenSearch description file with the - ``html_use_opensearch`` config value. - - You can now quickly include a logo in the sidebar, using the ``html_logo`` - config value. - - There are new blocks in the sidebar, so that you can easily insert content - into the sidebar. - -* LaTeX output: - - - The ``sphinx.sty`` package was cleaned of unused stuff. - - You can include a logo in the title page with the ``latex_logo`` config - value. - - You can define the link colors and a border and background color for - verbatim environments. - -Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and Sebastian -Wiesner for suggestions. - -Bugs fixed ----------- - -* sphinx.ext.autodoc: Don't check ``__module__`` for explicitly given - members. Remove "self" in class constructor argument list. - -* sphinx.htmlwriter: Don't use os.path for joining image HREFs. - -* sphinx.htmlwriter: Don't use SmartyPants for HTML attribute values. - -* sphinx.latexwriter: Implement option lists. Also, some other changes - were made to ``sphinx.sty`` in order to enhance compatibility and - remove old unused stuff. Thanks to Gael Varoquaux for that! - -* sphinx.roles: Fix referencing glossary terms with explicit targets. - -* sphinx.environment: Don't swallow TOC entries when resolving subtrees. - -* sphinx.quickstart: Create a sensible default latex_documents setting. - -* sphinx.builder, sphinx.environment: Gracefully handle some user error - cases. - -* sphinx.util: Follow symbolic links when searching for documents. - - -Release 0.1.61950 (Mar 26, 2008) -================================ - -* sphinx.quickstart: Fix format string for Makefile. - - -Release 0.1.61945 (Mar 26, 2008) -================================ - -* sphinx.htmlwriter, sphinx.latexwriter: Support the ``.. image::`` - directive by copying image files to the output directory. - -* sphinx.builder: Consistently name "special" HTML output directories - with a leading underscore; this means ``_sources`` and ``_static``. - -* sphinx.environment: Take dependent files into account when collecting - the set of outdated sources. - -* sphinx.directives: Record files included with ``.. literalinclude::`` - as dependencies. - -* sphinx.ext.autodoc: Record files from which docstrings are included - as dependencies. - -* sphinx.builder: Rebuild all HTML files in case of a template change. - -* sphinx.builder: Handle unavailability of TOC relations (previous/ - next chapter) more gracefully in the HTML builder. - -* sphinx.latexwriter: Include fncychap.sty which doesn't seem to be - very common in TeX distributions. Add a ``clean`` target in the - latex Makefile. Really pass the correct paper and size options - to the LaTeX document class. - -* setup: On Python 2.4, don't egg-depend on docutils if a docutils is - already installed -- else it will be overwritten. - - -Release 0.1.61843 (Mar 24, 2008) -================================ - -* sphinx.quickstart: Really don't create a makefile if the user - doesn't want one. - -* setup: Don't install scripts twice, via setuptools entry points - and distutils scripts. Only install via entry points. - -* sphinx.builder: Don't recognize the HTML builder's copied source - files (under ``_sources``) as input files if the source suffix is - ``.txt``. - -* sphinx.highlighting: Generate correct markup for LaTeX Verbatim - environment escapes even if Pygments is not installed. - -* sphinx.builder: The WebHTMLBuilder is now called PickleHTMLBuilder. - -* sphinx.htmlwriter: Make parsed-literal blocks work as expected, - not highlighting them via Pygments. - -* sphinx.environment: Don't error out on reading an empty source file. - - -Release 0.1.61798 (Mar 23, 2008) -================================ - -* sphinx: Work with docutils SVN snapshots as well as 0.4. - -* sphinx.ext.doctest: Make the group in which doctest blocks are - placed selectable, and default to ``'default'``. - -* sphinx.ext.doctest: Replace ```` in doctest blocks by - real blank lines for presentation output, and remove doctest - options given inline. - -* sphinx.environment: Move doctest_blocks out of block_quotes to - support indented doctest blocks. - -* sphinx.ext.autodoc: Render ``.. automodule::`` docstrings in a - section node, so that module docstrings can contain proper - sectioning. - -* sphinx.ext.autodoc: Use the module's encoding for decoding - docstrings, rather than requiring ASCII. - - -Release 0.1.61611 (Mar 21, 2008) -================================ - -* First public release. diff --git a/LICENSE b/LICENSE index 1442dea8fa0..12779b21370 100644 --- a/LICENSE +++ b/LICENSE @@ -34,79 +34,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Licenses for incorporated software ================================== -The included smartypants module, included as sphinx.util.smartypants, -is available under the following license: - ----------------------------------------------------------------------- -SmartyPants_ license:: - - Copyright (c) 2003 John Gruber - (https://daringfireball.net/projects/smartypants/) - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials - provided with the distribution. - - * Neither the name "SmartyPants" nor the names of its - contributors may be used to endorse or promote products - derived from this software without specific prior written - permission. - - This software is provided by the copyright holders and - contributors "as is" and any express or implied warranties, - including, but not limited to, the implied warranties of - merchantability and fitness for a particular purpose are - disclaimed. In no event shall the copyright owner or contributors - be liable for any direct, indirect, incidental, special, - exemplary, or consequential damages (including, but not limited - to, procurement of substitute goods or services; loss of use, - data, or profits; or business interruption) however caused and on - any theory of liability, whether in contract, strict liability, or - tort (including negligence or otherwise) arising in any way out of - the use of this software, even if advised of the possibility of - such damage. - - -smartypants.py license:: - - smartypants.py is a derivative work of SmartyPants. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials - provided with the distribution. - - This software is provided by the copyright holders and - contributors "as is" and any express or implied warranties, - including, but not limited to, the implied warranties of - merchantability and fitness for a particular purpose are - disclaimed. In no event shall the copyright owner or contributors - be liable for any direct, indirect, incidental, special, - exemplary, or consequential damages (including, but not limited - to, procurement of substitute goods or services; loss of use, - data, or profits; or business interruption) however caused and on - any theory of liability, whether in contract, strict liability, or - tort (including negligence or otherwise) arising in any way out of - the use of this software, even if advised of the possibility of - such damage. ----------------------------------------------------------------------- - The included implementation of NumpyDocstring._parse_numpydoc_see_also_section was derived from code under the following license: diff --git a/babel.cfg b/babel.cfg deleted file mode 100644 index b1816e80d21..00000000000 --- a/babel.cfg +++ /dev/null @@ -1,35 +0,0 @@ -# How to setup this file -# https://babel.pocoo.org/en/latest/installation.html -# this file description: -# https://babel.pocoo.org/en/latest/messages.html - -# Extraction from Python source files -[python: **.py] -encoding = utf-8 - -# Extraction from Jinja2 template files -[jinja2: **/templates/latex/**.tex_t] -variable_start_string = <%= -variable_end_string = %> -block_start_string = <% -block_end_string = %> - -# Extraction from Jinja2 template files -[jinja2: **/templates/latex/**.sty_t] -variable_start_string = <%= -variable_end_string = %> -block_start_string = <% -block_end_string = %> - -# Extraction from Jinja2 HTML templates -[jinja2: **/themes/**.html] -encoding = utf-8 -ignore_tags = script,style -include_attrs = alt title summary - -# Extraction from Jinja2 XML templates -[jinja2: **/themes/**.xml] - -# Extraction from JavaScript files -[javascript: **.js] -[javascript: **.js_t] diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt index 3077d1b9332..c5e75e05669 100644 --- a/doc/_static/conf.py.txt +++ b/doc/_static/conf.py.txt @@ -46,18 +46,18 @@ source_suffix = '.rst' root_doc = 'index' # General information about the project. -project = u'test' -copyright = u'2016, test' -author = u'test' +project = 'test' +copyright = '2016, test' +author = 'test' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = u'test' +version = 'test' # The full version, including alpha/beta/rc tags. -release = u'test' +release = 'test' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -131,7 +131,7 @@ html_theme = 'alabaster' # The name for this set of Sphinx documents. # " v documentation" by default. # -# html_title = u'test vtest' +# html_title = 'test vtest' # A shorter title for the navigation bar. Default is the same as html_title. # @@ -252,8 +252,8 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (root_doc, 'test.tex', u'test Documentation', - u'test', 'manual'), + (root_doc, 'test.tex', 'test Documentation', + 'test', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -283,7 +283,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (root_doc, 'test', u'test Documentation', + (root_doc, 'test', 'test Documentation', [author], 1) ] @@ -298,7 +298,7 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (root_doc, 'test', u'test Documentation', + (root_doc, 'test', 'test Documentation', author, 'test', 'One line description of project.', 'Miscellaneous'), ] diff --git a/doc/_themes/sphinx13/layout.html b/doc/_themes/sphinx13/layout.html index afab3693ba8..8010517a69a 100644 --- a/doc/_themes/sphinx13/layout.html +++ b/doc/_themes/sphinx13/layout.html @@ -32,7 +32,7 @@

      {{ _('Navigation') }}

      {%- block content %}