DOC: script to build single docstring page
State: closed

Add a way to build a single docstring page, without the need to build the full docs.



Labels:
name: Docs

Comments:
Hello @jorisvandenbossche! Thanks for updating the PR.





Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on February 26, 2018 at 18:30 Hours UTC
So for reference, @datapythonista 's approach is here: https://github.com/datapythonista/pandas/commit/5b4cc3ba4c48c497f93d31d8d4bfec16db4e046e

Comparing the two, I see you create a temp directory, copy/symlink those files you need, and then build there. 
I think this has the advantage that you can copy paste the existing `generated/pandas.[function/method].rst`, and don't need to manually create this, as I do. Because manually creating it has some weaknesses (I need to know whether it is a function or method, ...). 
The disadvantage of your approach is I think that you need already a full doc build, before you can use it?



> I think this has the advantage that you can copy paste the existing generated/pandas.[function/method].rst, and don't need to manually create this, as I do. Because manually creating it has some weaknesses (I need to know whether it is a function or method, ...).

I could of course also create manually a file that includes an `autosummary` table, so autosummary can just generate the correct file. 
Then the main problem is for the ones that have a custom template (eg some of our class docstrings and the accessor methods/attributes).
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19840?src=pr&el=h1) Report
> Merging [#19840](https://codecov.io/gh/pandas-dev/pandas/pull/19840?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/1e4c50a56f7e953ab84308f000dff6fc1ac71171?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/19840/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/19840?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #19840   +/-   ##
=======================================
  Coverage   91.66%   91.66%           
=======================================
  Files         150      150           
  Lines       48969    48969           
=======================================
  Hits        44886    44886           
  Misses       4083     4083
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.04% <ø> (ø)` | :arrow_up: |
| #single | `41.85% <ø> (ø)` | :arrow_up: |


------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19840?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19840?src=pr&el=footer). Last update [1e4c50a...ebe4a8b](https://codecov.io/gh/pandas-dev/pandas/pull/19840?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

So I updated this to somehow a hybrid approach from what I did and @datapythonista did (symlinking/copying existing files).
Also added the ability to build multiple docstrings at once, so you can do eg:

```
python make.py --docstring pandas.DataFrame.sort_values pandas.Series.sort_values
```


some linting issues, otherwise lgtm.

```
doc/make.py:21:1: F811 redefinition of unused 'shutil' from line 16
doc/source/conf.py:21:1: F401 'pandas.compat.PY3' imported but unused
```
Works great, nice approach.

It doesn't make a big difference, but IMO it'd be simpler and somehow more consistent to use `./make.py html --single pandas.DataFrame.sort_values`. I think it's easy to detect if the parameter of `single` is a `.rst` documentation page, a pandas method/function or nothing (and in this case it could show a descriptive error, useful if users try `DataFrame.sort_values` without the pandas before).

Also, I think this would avoid having to modify the main function, which I think it makes the code easier if it' keeps generic.

But anyway, I think it's a great and very useful PR. Let me know if you agree with my comments but you don't have time to make the changes, happy to do them myself.
@datapythonista Thanks for testing!

The 'problem' with integrating it into `--single`, is that I do some things differently. Eg in the main function, I call `_generate_index(single_doc='temp.rst')` instead of `_generate_index(single_doc=args.single)` (so a hardcoded value). So I would need to do some if checks on what `args.single` is inside the main function anyway I think?

But I can move some parts that are now in the main function (eg the browser opening and removal of files) to the `build_docstring` function, that would keep the main function already cleaner.
@jorisvandenbossche I tested if we could use `--single` by trying to use `index.rst.template` and the `exclude_pattern` system you implemented, and I think it's simpler and still works well/fast as your version.

I created a new PR, #19864, so you can check it.
@datapythonista this is ready for another look 
Was there other functionality that you wanted to add?