質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

新規登録して質問してみよう
ただいま回答率
86.12%
reStructuredText

reStructuredText(reST)は、軽量マークアップ言語です。一般的にはSphinxというビルドプラットフォームでビルドして、HTMLやPDFなどの出版形式に変換して使用されます。

makefile

make は、プログラムのビルド作業を自動化するツールです。コンパイル、リンク、インストール等のルールを記述したテキストファイルをmakefileと呼び、このルールに従ってmakeが自動的にビルドを実行する。

Python

Pythonは、コードの読みやすさが特徴的なプログラミング言語の1つです。 強い型付け、動的型付けに対応しており、後方互換性がないバージョン2系とバージョン3系が使用されています。 商用製品の開発にも無料で使用でき、OSだけでなく仮想環境にも対応。Unicodeによる文字列操作をサポートしているため、日本語処理も標準で可能です。

HTML

HTMLとは、ウェブ上の文書を記述・作成するためのマークアップ言語のことです。文章の中に記述することで、文書の論理構造などを設定することができます。ハイパーリンクを設定できるハイパーテキストであり、画像・リスト・表などのデータファイルをリンクする情報に結びつけて情報を整理します。現在あるネットワーク上のほとんどのウェブページはHTMLで作成されています。

解決済

sphinxの使い方について

wa20ta_mzn
wa20ta_mzn

総合スコア23

reStructuredText

reStructuredText(reST)は、軽量マークアップ言語です。一般的にはSphinxというビルドプラットフォームでビルドして、HTMLやPDFなどの出版形式に変換して使用されます。

makefile

make は、プログラムのビルド作業を自動化するツールです。コンパイル、リンク、インストール等のルールを記述したテキストファイルをmakefileと呼び、このルールに従ってmakeが自動的にビルドを実行する。

Python

Pythonは、コードの読みやすさが特徴的なプログラミング言語の1つです。 強い型付け、動的型付けに対応しており、後方互換性がないバージョン2系とバージョン3系が使用されています。 商用製品の開発にも無料で使用でき、OSだけでなく仮想環境にも対応。Unicodeによる文字列操作をサポートしているため、日本語処理も標準で可能です。

HTML

HTMLとは、ウェブ上の文書を記述・作成するためのマークアップ言語のことです。文章の中に記述することで、文書の論理構造などを設定することができます。ハイパーリンクを設定できるハイパーテキストであり、画像・リスト・表などのデータファイルをリンクする情報に結びつけて情報を整理します。現在あるネットワーク上のほとんどのウェブページはHTMLで作成されています。

1回答

0リアクション

0クリップ

176閲覧

投稿2022/08/28 10:41

前提

sphinxでpythonコードから文書を作りたい。

実現したいこと

https://qiita.com/futakuchi0117/items/4d3997c1ca1323259844
を参考にしてpythonファイルから文書を生成したいです。

試したこと


URLを参考に作業ディレクトリをsphinx1として、中にdocsディレクトリとmain.pyを作成しました。
その後下記を実行。

python

$ sphinx-quickstart docs

実行後の構成は以下の通りでした。

C:. │ main.py │ └─docs │ make.bat │ Makefile │ ├─build └─source │ conf.py │ index.rst │ ├─_static └─_templates

バージョンが違うせいか、作成されたディレクトリは形式が違うようでした。


次にconf.pyを編集しました。

python

# Configuration file for the Sphinx documentation builder. # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'hoge' copyright = '2022, hogehoge' author = 'hogehoge' import os import sys sys.path.insert(0, os.path.abspath('../../')) # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon' ] templates_path = ['_templates'] exclude_patterns = [] language = 'ja' # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = 'sphinx_rtd_theme' html_static_path = ['_static']

参考URLにはimport os以下3行を書き換えるよう書いてあったのですが、
何も記載がなかったためとりあえず3行分を新たに追加しました。

『conf.pyから見て1つ上のディレクトリ内のpythonファイルを読み込むため,そのpath(../)を指定します.』
今回はcon.pyはsourceディレクトリ内に入っているため、main.pyを参照するためにpathは(../../)としました。
あとはextensionsとhtml_themeをURL通りに書きかえました。


次にrstを編集しました。今回はmainを読み込むためmainを追加しました。
(これはmain.pyなのか後でつくるmain.rstのことなのか…)

rst

Welcome to hoge's documentation! ================================ .. toctree:: :maxdepth: 2 :caption: Contents: main Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`


そしてrstファイル作成のために下記を実行しました。

C:\Users\xxxxxxx\Documents\sphinx1>sphinx-apidoc -f -o ./docs . Creating file ./docs\main.rst. Creating file ./docs\modules.rst.

実行後docsディレクトリに
main.rstとmodules.rstが作成されました。

⑤最後にrstファイルをもとにhtmlファイルを生成します。
見本は下記のようになっていました。

sphinx-build -b singlehtml ./docs ./docs/_build

ただ今回は_buildというハイフンつきのディレクトリは存在せずbuildだけだったので、

下記を実行しました。

C:\Users\xxxxxx\Documents\sphinx1>sphinx-build -b singlehtml ./docs ./docs/build Running Sphinx v5.1.1 Configuration error: config directory doesn't contain a conf.py file (C:\Users\xxxxx\Documents\sphinx1\docs)

今回はconf.pyがsource内に入っているため再度下記を実行しました。

C:\Users\xxxxxx\Documents\sphinx1>sphinx-build -b singlehtml ./docs/source ./docs/build Running Sphinx v5.1.1 loading translations [ja]... done building [mo]: targets for 0 po files that are out of date building [singlehtml]: all documents updating environment: [new config] 1 added, 0 changed, 0 removed reading sources... [100%] index C:\Users\xxxxx\Documents\sphinx1\docs\source\index.rst:9: WARNING: toctree contains reference to nonexisting document 'main' looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done assembling single document... done writing... done writing additional files... done copying static files... done copying extra files... done dumping object inventory... done build succeeded, 1 warning. The HTML page is in docs\build.

すると…index.rstにエラーメッセージが出ているみたいでmainを見つけられないと出てしまいました。
③で編集したrstの書き方が間違っているのか、main.rstを探している場所が違うのか…。

参考URLだとdocs内にindex.rstがあり、
今回作成したmain.rstも同じディレクトリ内にあるので、
main.rstとmodule.rstをsource内に移動しました。

そして再度実行。

C:\Users\xxxxxxx\Documents\sphinx1>sphinx-build -b singlehtml ./docs/source ./docs/build Running Sphinx v5.1.1 loading translations [ja]... done loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [singlehtml]: all documents updating environment: 2 added, 1 changed, 0 removed reading sources... [100%] modules looking for now-outdated files... none found pickling environment... done checking consistency... C:\Users\xxxxxxx\Documents\sphinx1\docs\source\modules.rst: WARNING: document isn't included in any toctree done preparing documents... done assembling single document... main done writing... done writing additional files... done copying static files... done copying extra files... done dumping object inventory... done build succeeded, 1 warning. The HTML page is in docs\build.

一応htmlファイルが作成されたみたいです。
C:\Users\xxxxx\Documents\sphinx1\docs\source\modules.rst: WARNING: document isn't included in any toctree
上記のwarning文だけが気になっている状態です。

一応質問文を書いている途中に色々試しながらhtmlファイルまで作ることができました。
そのためあと数日でこの質問は自己解決にしようと思っています。
ここまでのやり方で何か変なやり方をしている場合はアドバイスいただけますと幸いです。

補足情報(FW/ツールのバージョンなど)

環境
Windows 10
Python 3.6.1
Sphinx 5.1.1

pip

Sphinx==5.1.1 sphinx-rtd-theme==1.0.0 sphinxcontrib-applehelp==1.0.2 sphinxcontrib-blockdiag==2.0.0 sphinxcontrib-devhelp==1.0.2 sphinxcontrib-htmlhelp==2.0.0 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.3 sphinxcontrib-serializinghtml==1.1.5

以下のような質問にはリアクションをつけましょう

  • 質問内容が明確
  • 自分も答えを知りたい
  • 質問者以外のユーザにも役立つ

リアクションが多い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

気になる質問をクリップする

クリップした質問は、後からいつでもマイページで確認できます。

またクリップした質問に回答があった際、通知やメールを受け取ることができます。

下記のような質問は推奨されていません。

  • 間違っている
  • 質問になっていない投稿
  • スパムや攻撃的な表現を用いた投稿

適切な質問に修正を依頼しましょう。

2022/08/28 12:59

こちらの質問が他のユーザーから「問題・課題が含まれていない質問」という指摘を受けました。

wa20ta_mzn

2022/09/17 10:13

引用元のサイトの > Separate source and build directories (y/n) [n]: ソースとビルドのディレクトリを完全に分けるかどうか. デフォルトだとソースフォルダ内に_buildディレクトリができます. ここの部分で作成されるフォルダが変わってたんですね。 私はyを選んでいたので上記内容の構成になったようです。

まだ回答がついていません

会員登録して回答してみよう

アカウントをお持ちの方は

15分調べてもわからないことは
teratailで質問しよう!

ただいまの回答率
86.12%

質問をまとめることで
思考を整理して素早く解決

テンプレート機能で
簡単に質問をまとめる

質問する

関連した質問

同じタグがついた質問を見る

reStructuredText

reStructuredText(reST)は、軽量マークアップ言語です。一般的にはSphinxというビルドプラットフォームでビルドして、HTMLやPDFなどの出版形式に変換して使用されます。

makefile

make は、プログラムのビルド作業を自動化するツールです。コンパイル、リンク、インストール等のルールを記述したテキストファイルをmakefileと呼び、このルールに従ってmakeが自動的にビルドを実行する。

Python

Pythonは、コードの読みやすさが特徴的なプログラミング言語の1つです。 強い型付け、動的型付けに対応しており、後方互換性がないバージョン2系とバージョン3系が使用されています。 商用製品の開発にも無料で使用でき、OSだけでなく仮想環境にも対応。Unicodeによる文字列操作をサポートしているため、日本語処理も標準で可能です。

HTML

HTMLとは、ウェブ上の文書を記述・作成するためのマークアップ言語のことです。文章の中に記述することで、文書の論理構造などを設定することができます。ハイパーリンクを設定できるハイパーテキストであり、画像・リスト・表などのデータファイルをリンクする情報に結びつけて情報を整理します。現在あるネットワーク上のほとんどのウェブページはHTMLで作成されています。